docs: Add charm linking guide #2155

tonyespinoza1 · 2025-11-24T22:14:28Z

Summary

Add comprehensive documentation for charm linking in CommonTools patterns
Covers source charms (data providers), consumer charms (data receivers), and the linking workflow
Includes complete working examples with deployment scripts

Source Charm Creation - How to expose data with Output interfaces
Consumer Charm Creation - How to receive linked data with Default<T, null>
Deployment & Linking - CLI commands for ct charm new and ct charm link
Complete Example - Full GPA stats source/reader pattern pair
Quick Reference - Checklists and common type patterns

Test plan

Review documentation for accuracy
Verify code examples compile correctly
Check that CLI command syntax is correct

🤖 Generated with Claude Code

Summary by cubic

Add a Charm Linking Guide to the docs with step-by-step instructions and examples for linking source and consumer charms in CommonTools. Includes Output/Input interface patterns, reactive linking, CLI commands (ct charm new/link), a full GPA stats example with a deployment script, and quick-reference checklists.

^{Written for commit e4e2709. Summary will update automatically on new commits.}

Add comprehensive documentation for charm linking in CommonTools patterns, covering how to create source charms that expose data, consumer charms that receive linked data, and the CLI commands for deploying and linking charms. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Update browser access URLs to use port 8000 instead of 5173, reflecting the upcoming convention change. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

cubic-dev-ai

2 issues found across 1 file

Prompt for AI agents (all 2 issues)


Understand the root cause of the following 2 issues and fix them.


<file name="docs/common/CHARM_LINKING.md">

<violation number="1" location="docs/common/CHARM_LINKING.md:61">
The source-charm example calls a `percentile` helper that is never defined, so the sample code cannot compile or run as written.</violation>

<violation number="2" location="docs/common/CHARM_LINKING.md:73">
The guide’s source-charm recipe invokes `parseData(rawData)` without ever defining that helper, so the example cannot be executed as provided.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

cubic-dev-ai · 2025-11-24T22:24:06Z

docs/common/CHARM_LINKING.md

+  "Stats Calculator",
+  ({ name, rawData }) => {
+    // Compute derived values
+    const parsedValues = parseData(rawData);


The guide’s source-charm recipe invokes parseData(rawData) without ever defining that helper, so the example cannot be executed as provided.

Prompt for AI agents

Address the following comment on docs/common/CHARM_LINKING.md at line 73: <comment>The guide’s source-charm recipe invokes `parseData(rawData)` without ever defining that helper, so the example cannot be executed as provided.</comment> <file context> @@ -0,0 +1,447 @@ + "Stats Calculator", + ({ name, rawData }) => { + // Compute derived values + const parsedValues = parseData(rawData); + const computedStats = calculateStats(parsedValues); + </file context>

✅ Addressed in 94cdcac

cubic-dev-ai · 2025-11-24T22:24:06Z

docs/common/CHARM_LINKING.md

+  const average = sum / n;
+
+  // Quartile calculations...
+  const q1 = percentile(sorted, 25);


The source-charm example calls a percentile helper that is never defined, so the sample code cannot compile or run as written.

Prompt for AI agents

Address the following comment on docs/common/CHARM_LINKING.md at line 61: <comment>The source-charm example calls a `percentile` helper that is never defined, so the sample code cannot compile or run as written.</comment> <file context> @@ -0,0 +1,447 @@ + const average = sum / n; + + // Quartile calculations... + const q1 = percentile(sorted, 25); + const median = percentile(sorted, 50); + const q3 = percentile(sorted, 75); </file context>

✅ Addressed in 94cdcac

cubic-dev-ai

2 issues found across 1 file

Prompt for AI agents (all 2 issues)


Understand the root cause of the following 2 issues and fix them.


<file name="docs/common/CHARM_LINKING.md">

<violation number="1" location="docs/common/CHARM_LINKING.md:61">
The documentation references an undefined `percentile` helper in the source-charm example, making the sample code invalid.</violation>

<violation number="2" location="docs/common/CHARM_LINKING.md:73">
The Stats source-charm example calls `parseData` without providing an implementation, so the documented code cannot compile as written.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

cubic-dev-ai · 2025-11-24T22:32:06Z

docs/common/CHARM_LINKING.md

+  const average = sum / n;
+
+  // Quartile calculations...
+  const q1 = percentile(sorted, 25);


The documentation references an undefined percentile helper in the source-charm example, making the sample code invalid.

Prompt for AI agents

Address the following comment on docs/common/CHARM_LINKING.md at line 61: <comment>The documentation references an undefined `percentile` helper in the source-charm example, making the sample code invalid.</comment> <file context> @@ -0,0 +1,447 @@ + const average = sum / n; + + // Quartile calculations... + const q1 = percentile(sorted, 25); + const median = percentile(sorted, 50); + const q3 = percentile(sorted, 75); </file context>

✅ Addressed in 94cdcac

cubic-dev-ai · 2025-11-24T22:32:06Z

docs/common/CHARM_LINKING.md

+  "Stats Calculator",
+  ({ name, rawData }) => {
+    // Compute derived values
+    const parsedValues = parseData(rawData);


The Stats source-charm example calls parseData without providing an implementation, so the documented code cannot compile as written.

Prompt for AI agents

Address the following comment on docs/common/CHARM_LINKING.md at line 73: <comment>The Stats source-charm example calls `parseData` without providing an implementation, so the documented code cannot compile as written.</comment> <file context> @@ -0,0 +1,447 @@ + "Stats Calculator", + ({ name, rawData }) => { + // Compute derived values + const parsedValues = parseData(rawData); + const computedStats = calculateStats(parsedValues); + </file context>

✅ Addressed in 94cdcac

seefeldb · 2025-11-24T23:05:45Z

docs/common/CHARM_LINKING.md

+  return { average, q1, median, q3, iqr, count: n };
+});
+
+export default recipe<Input, Output>(


let's switch to pattern, which also means leaving out the title in the next line.

You can add the title back in the input schema via jsdoc: Write /** Stats Calculator */ right above defining the Input type.

docs/common/CHARM_LINKING.md

seefeldb · 2025-11-24T23:08:06Z

docs/common/CHARM_LINKING.md

+export default recipe<Input, Input>(
+  "Stats Reader",
+  ({ name, linkedStats }) => {
+    const dataPresent = hasData(linkedStats);


this is unused and honestly also a distraction, i'd remove this here and above

seefeldb · 2025-11-24T23:09:05Z

docs/common/CHARM_LINKING.md

+```typescript
+// Helper functions handle null gracefully
+const hasData = lift((s: Stats | null) => s !== null);
+const getAverage = lift((s: Stats | null) => s?.average);


getAverage that just reads a property is not necessary, you can just write formatNumber(linkedStats.average) below in the JSX

seefeldb · 2025-11-24T23:09:36Z

docs/common/CHARM_LINKING.md

+
+1. **Use `Default<T, null>` for linked fields** - provides fallback when unlinked
+2. **Interface must match source** - the Stats interface must be identical
+3. **Use `lift()` for null-safe access** - `lift((s) => s?.field)` handles null gracefully


remove this third point.

seefeldb · 2025-11-24T23:10:03Z

docs/common/CHARM_LINKING.md

+1. **Use `Default<T, null>` for linked fields** - provides fallback when unlinked
+2. **Interface must match source** - the Stats interface must be identical
+3. **Use `lift()` for null-safe access** - `lift((s) => s?.field)` handles null gracefully
+4. **Show helpful UI when unlinked** - guide users on how to link


do we want that guidance? seems misplaced to me...

seefeldb

some minor suggestions

- Change `recipe` to `pattern` throughout all examples - Add JSDoc comments above Input interfaces for charm titles - Add missing `parseData` lifted function implementation - Inline `percentile` helper inside `calculateStats` function - Update Quick Reference checklist to mention `pattern` and JSDoc 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

- Remove third point about lift() for null-safe access from Key Rules - Remove fourth point about showing helpful UI when unlinked - Remove unused hasData and getAverage helpers from consumer example - Simplify consumer example to use linkedStats?.average directly - Add note about importing Stats type from source charm - Update Consumer Charm Checklist to be more concise 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

tonyespinoza1 temporarily deployed to ci November 24, 2025 22:18 — with GitHub Actions Inactive

docs: Update charm linking guide to use port 8000

460f912

Update browser access URLs to use port 8000 instead of 5173, reflecting the upcoming convention change. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

cubic-dev-ai bot reviewed Nov 24, 2025

View reviewed changes

tonyespinoza1 temporarily deployed to ci November 24, 2025 22:27 — with GitHub Actions Inactive

cubic-dev-ai bot reviewed Nov 24, 2025

View reviewed changes

seefeldb reviewed Nov 24, 2025

View reviewed changes

docs/common/CHARM_LINKING.md Show resolved Hide resolved

seefeldb reviewed Nov 24, 2025

View reviewed changes

seefeldb approved these changes Nov 24, 2025

View reviewed changes

tonyespinoza1 temporarily deployed to ci November 24, 2025 23:20 — with GitHub Actions Inactive

tonyespinoza1 temporarily deployed to ci November 24, 2025 23:33 — with GitHub Actions Inactive

tonyespinoza1 merged commit c0fcf80 into main Nov 24, 2025
10 checks passed

tonyespinoza1 deleted the docs/charm-linking-guide branch November 24, 2025 23:41

docs: Add charm linking guide #2155

docs: Add charm linking guide #2155

Uh oh!

Conversation

tonyespinoza1 commented Nov 24, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Contents

Test plan

Summary by cubic

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seefeldb Nov 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

seefeldb Nov 24, 2025

Choose a reason for hiding this comment

Uh oh!

seefeldb Nov 24, 2025

Choose a reason for hiding this comment

Uh oh!

seefeldb Nov 24, 2025

Choose a reason for hiding this comment

Uh oh!

seefeldb Nov 24, 2025

Choose a reason for hiding this comment

Uh oh!

seefeldb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tonyespinoza1 commented Nov 24, 2025 •

edited by cubic-dev-ai bot

Loading

cubic-dev-ai bot Nov 24, 2025 •

edited

Loading

cubic-dev-ai bot Nov 24, 2025 •

edited

Loading

cubic-dev-ai bot Nov 24, 2025 •

edited

Loading

cubic-dev-ai bot Nov 24, 2025 •

edited

Loading