capdag 0.100.226 → 0.102.232

package/capdag.js

@@ -1222,13 +1222,14 @@ class MediaSpec {
    * @param {string|null} profile - Optional profile URL
    * @param {Object|null} schema - Optional JSON Schema for local validation
    * @param {string|null} title - Optional display-friendly title
-   * @param {string|null} description - Optional description
+   * @param {string|null} description - Optional short plain-text description
    * @param {string|null} mediaUrn - Source media URN for tag-based checks
    * @param {Object|null} validation - Optional validation rules (min, max, min_length, max_length, pattern, allowed_values)
    * @param {Object|null} metadata - Optional metadata (arbitrary key-value pairs for display/categorization)
    * @param {string[]} extensions - File extensions for storing this media type (e.g., ['pdf'], ['jpg', 'jpeg'])
+   * @param {string|null} documentation - Optional long-form markdown documentation. Rendered in media info panels, the cap navigator, capdag-dot-com, and anywhere else a rich-text explanation of the media spec is useful.
    */
-  constructor(contentType, profile = null, schema = null, title = null, description = null, mediaUrn = null, validation = null, metadata = null, extensions = []) {
+  constructor(contentType, profile = null, schema = null, title = null, description = null, mediaUrn = null, validation = null, metadata = null, extensions = [], documentation = null) {
     this.contentType = contentType;
     this.profile = profile;
     this.schema = schema;
@@ -1238,6 +1239,7 @@ class MediaSpec {
     this.validation = validation;
     this.metadata = metadata;
     this.extensions = extensions;
+    this.documentation = documentation;
   }
 
   /**
@@ -1387,12 +1389,19 @@ function resolveMediaUrn(mediaUrn, mediaSpecs = []) {
     const def = mediaSpecs.find(spec => spec.urn === mediaUrn);
 
     if (def) {
-      // Object form: { urn, media_type, title, profile_uri?, schema?, description?, validation?, metadata?, extensions? }
+      // Object form: { urn, media_type, title, profile_uri?, schema?, description?, documentation?, validation?, metadata?, extensions? }
       const mediaType = def.media_type || def.mediaType;
       const profileUri = def.profile_uri || def.profileUri || null;
       const schema = def.schema || null;
       const title = def.title || null;
       const description = def.description || null;
+      // Long-form markdown body for rich info panels. Strict
+      // snake_case (`documentation`) to match the JSON schema; no
+      // camelCase fallback because all generator pipelines write the
+      // canonical form.
+      const documentation = typeof def.documentation === 'string' && def.documentation.length > 0
+        ? def.documentation
+        : null;
       const validation = def.validation || null;
       const metadata = def.metadata || null;
       const extensions = Array.isArray(def.extensions) ? def.extensions : [];
@@ -1404,7 +1413,7 @@ function resolveMediaUrn(mediaUrn, mediaSpecs = []) {
         );
       }
 
-      return new MediaSpec(mediaType, profileUri, schema, title, description, mediaUrn, validation, metadata, extensions);
+      return new MediaSpec(mediaType, profileUri, schema, title, description, mediaUrn, validation, metadata, extensions, documentation);
     }
   }
 
@@ -1888,11 +1897,12 @@ class Cap {
    * @param {CapUrn} urn - The capability URN
    * @param {string} title - The human-readable title (required)
    * @param {string} command - The command string
-   * @param {string|null} capDescription - Optional description
+   * @param {string|null} capDescription - Optional short plain-text description
    * @param {Object} metadata - Optional metadata object
    * @param {Object|null} metadataJson - Optional arbitrary metadata as JSON object
+   * @param {string|null} documentation - Optional long-form markdown documentation. Rendered in capability info panels, the cap navigator, capdag-dot-com, and anywhere else a rich-text explanation of the cap is useful.
    */
-  constructor(urn, title, command, capDescription = null, metadata = {}, metadataJson = null) {
+  constructor(urn, title, command, capDescription = null, metadata = {}, metadataJson = null, documentation = null) {
     if (!(urn instanceof CapUrn)) {
       throw new Error('URN must be a CapUrn instance');
     }
@@ -1907,6 +1917,7 @@ class Cap {
     this.title = title;
     this.command = command;
     this.cap_description = capDescription;
+    this.documentation = documentation;
     this.metadata = metadata || {};
     this.mediaSpecs = [];  // Media spec definitions array
     this.args = [];  // Array of CapArg - unified argument format
@@ -1915,6 +1926,31 @@ class Cap {
     this.registered_by = null;  // Registration attribution
   }
 
+  /**
+   * Get the long-form markdown documentation, if any.
+   * @returns {string|null}
+   */
+  getDocumentation() {
+    return this.documentation;
+  }
+
+  /**
+   * Set the long-form markdown documentation.
+   * @param {string|null} documentation
+   */
+  setDocumentation(documentation) {
+    this.documentation = (typeof documentation === 'string' && documentation.length > 0)
+      ? documentation
+      : null;
+  }
+
+  /**
+   * Clear the long-form markdown documentation.
+   */
+  clearDocumentation() {
+    this.documentation = null;
+  }
+
   /**
    * Get the media type expected for stdin (derived from args with stdin source)
    * @returns {string|null} The media URN for stdin, or null if cap doesn't accept stdin
@@ -2098,6 +2134,7 @@ class Cap {
            this.title === other.title &&
            this.command === other.command &&
            this.cap_description === other.cap_description &&
+           this.documentation === other.documentation &&
            JSON.stringify(this.metadata) === JSON.stringify(other.metadata) &&
            JSON.stringify(this.mediaSpecs) === JSON.stringify(other.mediaSpecs) &&
            JSON.stringify(this.args.map(a => a.toJSON())) === JSON.stringify(other.args.map(a => a.toJSON())) &&
@@ -2122,6 +2159,12 @@ class Cap {
       output: this.output
     };
 
+    // Long-form markdown documentation. Only emitted when set, to match
+    // the Rust serializer which skips this field when None.
+    if (typeof this.documentation === 'string' && this.documentation.length > 0) {
+      result.documentation = this.documentation;
+    }
+
     if (this.metadata_json !== null && this.metadata_json !== undefined) {
       result.metadata_json = this.metadata_json;
     }
@@ -2141,7 +2184,10 @@ class Cap {
     }
     const urn = CapUrn.fromString(json.urn);
 
-    const cap = new Cap(urn, json.title, json.command, json.cap_description, json.metadata, json.metadata_json);
+    const documentation = (typeof json.documentation === 'string' && json.documentation.length > 0)
+      ? json.documentation
+      : null;
+    const cap = new Cap(urn, json.title, json.command, json.cap_description, json.metadata, json.metadata_json, documentation);
     cap.mediaSpecs = json.media_specs || json.mediaSpecs || [];
     // Parse args (new format)
     if (json.args && Array.isArray(json.args)) {
@@ -4648,6 +4694,64 @@ class Machine {
     return lines.join('\n');
   }
 
+  /**
+   * Serialize this machine graph to machine notation in the specified format.
+   *
+   * The output is deterministic: same graph + same format → same string.
+   * @param {'bracketed' | 'line-based'} format - The notation format to use.
+   * @returns {string}
+   */
+  toMachineNotationFormatted(format) {
+    if (this._edges.length === 0) {
+      return '';
+    }
+
+    const { aliases, nodeNames, edgeOrder } = this._buildSerializationMaps();
+    const bracketed = format === 'bracketed';
+    const open = bracketed ? '[' : '';
+    const close = bracketed ? ']' : '';
+    const lines = [];
+
+    // Emit headers in alias-sorted order
+    const sortedAliases = Array.from(aliases.entries()).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+
+    for (const [alias, { edgeIdx }] of sortedAliases) {
+      const edge = this._edges[edgeIdx];
+      lines.push(`${open}${alias} ${edge.capUrn}${close}`);
+    }
+
+    // Emit wirings in edge order
+    for (const edgeIdx of edgeOrder) {
+      const edge = this._edges[edgeIdx];
+      let alias = null;
+      for (const [a, info] of aliases) {
+        if (info.edgeIdx === edgeIdx) {
+          alias = a;
+          break;
+        }
+      }
+
+      const sources = edge.sources.map(s => {
+        const key = s.toString();
+        return nodeNames.get(key);
+      });
+
+      const targetKey = edge.target.toString();
+      const targetName = nodeNames.get(targetKey);
+
+      const loopPrefix = edge.isLoop ? 'LOOP ' : '';
+
+      if (sources.length === 1) {
+        lines.push(`${open}${sources[0]} -> ${loopPrefix}${alias} -> ${targetName}${close}`);
+      } else {
+        const group = sources.join(', ');
+        lines.push(`${open}(${group}) -> ${loopPrefix}${alias} -> ${targetName}${close}`);
+      }
+    }
+
+    return bracketed ? lines.join('') : lines.join('\n');
+  }
+
   /**
    * Build the alias map, node name map, and edge ordering for serialization.
    *

package/capdag.test.js

@@ -1836,6 +1836,86 @@ function testJS_capJSONSerialization() {
   assertEqual(restored.urn.getOutSpec(), MEDIA_OBJECT, 'Should restore outSpec');
 }
 
+// JS round-trip for the documentation field on Cap. Mirrors TEST920 in
+// capdag/src/cap/definition.rs — the body is non-trivial (newlines,
+// backticks, embedded quotes, Unicode) so escaping mismatches between
+// JSON.stringify on this side and the Rust serializer on the other side
+// surface as failures here.
+function testJS_capDocumentationRoundTrip() {
+  const urn = CapUrn.fromString(testUrn('op=documented'));
+  const cap = new Cap(urn, 'Documented Cap', 'documented');
+  const body = '# Documented Cap\r\n\nDoes the thing.\n\n```bash\necho "hi"\n```\n\nSee also: \u2605\n';
+  cap.setDocumentation(body);
+  assertEqual(cap.getDocumentation(), body, 'Setter must store the body verbatim');
+
+  const json = cap.toJSON();
+  assertEqual(json.documentation, body, 'toJSON must include documentation when set');
+
+  // Stringify and parse to simulate writing to disk and reading back.
+  const wireJson = JSON.parse(JSON.stringify(json));
+  const restored = Cap.fromJSON(wireJson);
+  assertEqual(restored.getDocumentation(), body, 'fromJSON must preserve documentation body verbatim');
+  assert(restored.equals(cap), 'Round-tripped cap must equal the original');
+}
+
+// When documentation is null, toJSON must omit the field entirely. This
+// matches the Rust serializer's skip-when-None semantics and the ObjC
+// toDictionary behaviour. A regression where null is emitted as
+// `documentation: null` would break the symmetric round-trip with Rust
+// (which has no null sentinel) and pollute generated JSON.
+function testJS_capDocumentationOmittedWhenNull() {
+  const urn = CapUrn.fromString(testUrn('op=undocumented'));
+  const cap = new Cap(urn, 'Undocumented Cap', 'undocumented');
+  assertEqual(cap.getDocumentation(), null, 'Default documentation must be null');
+
+  const json = cap.toJSON();
+  assert(!('documentation' in json), 'toJSON must omit documentation key when null');
+
+  // fromJSON of a missing key must yield null, not undefined or empty string.
+  const restored = Cap.fromJSON(JSON.parse(JSON.stringify(json)));
+  assertEqual(restored.getDocumentation(), null, 'Missing documentation must round-trip as null');
+
+  // Empty-string body is treated as absent (matches the resolver's
+  // non-empty-string-only rule). This catches code paths that would store
+  // an empty string and then emit it as a literal field.
+  cap.setDocumentation('');
+  assertEqual(cap.getDocumentation(), null, 'Empty string must collapse to null');
+}
+
+// Documentation propagates from a mediaSpecs definition through
+// resolveMediaUrn into the resolved MediaSpec. Mirrors TEST924 on the Rust
+// side. This is the path every UI consumer uses, so a break here makes the
+// new field invisible everywhere downstream.
+function testJS_mediaSpecDocumentationPropagatesThroughResolve() {
+  const body = '## Markdown body\n\nWith `code` and a [link](https://example.com).';
+  const mediaSpecs = [
+    {
+      urn: 'media:doc-test;textable',
+      media_type: 'text/plain',
+      title: 'Documented',
+      description: 'short desc',
+      documentation: body
+    }
+  ];
+
+  const resolved = resolveMediaUrn('media:doc-test;textable', mediaSpecs);
+  assertEqual(resolved.documentation, body, 'documentation must propagate into MediaSpec');
+  // The short description must remain distinct from the long markdown
+  // body — they are different fields with different semantics.
+  assertEqual(resolved.description, 'short desc', 'description must remain distinct from documentation');
+
+  // Missing documentation must collapse to null, not '' or undefined.
+  const noDoc = resolveMediaUrn('media:doc-test;textable', [
+    { urn: 'media:doc-test;textable', media_type: 'text/plain', title: 'No Doc' }
+  ]);
+  assertEqual(noDoc.documentation, null, 'Missing documentation must resolve to null');
+
+  const emptyDoc = resolveMediaUrn('media:doc-test;textable', [
+    { urn: 'media:doc-test;textable', media_type: 'text/plain', title: 'Empty', documentation: '' }
+  ]);
+  assertEqual(emptyDoc.documentation, null, 'Empty documentation string must collapse to null');
+}
+
 function testJS_stdinSourceKindConstants() {
   assert(StdinSourceKind.DATA !== undefined, 'DATA kind should be defined');
   assert(StdinSourceKind.FILE_REFERENCE !== undefined, 'FILE_REFERENCE kind should be defined');
@@ -2793,6 +2873,117 @@ function testMachine_unterminatedBracketFails() {
   );
 }
 
+// --- Machine parser line-based mode tests ---
+
+function testMachine_lineBasedSimpleChain() {
+  const g = Machine.fromString(
+    'extract cap:in="media:pdf";op=extract;out="media:txt;textable"\n' +
+    'doc -> extract -> text'
+  );
+  assertEqual(g.edgeCount(), 1);
+  const edge = g.edges()[0];
+  assert(edge.sources[0].isEquivalent(MediaUrn.fromString('media:pdf')),
+    'Source should be media:pdf');
+  assert(edge.target.isEquivalent(MediaUrn.fromString('media:txt;textable')),
+    'Target should be media:txt;textable');
+}
+
+function testMachine_lineBasedTwoStepChain() {
+  const g = Machine.fromString(
+    'extract cap:in="media:pdf";op=extract;out="media:txt;textable"\n' +
+    'embed cap:in="media:txt;textable";op=embed;out="media:embedding-vector;record;textable"\n' +
+    'doc -> extract -> text\n' +
+    'text -> embed -> vectors'
+  );
+  assertEqual(g.edgeCount(), 2);
+}
+
+function testMachine_lineBasedLoop() {
+  const g = Machine.fromString(
+    'p2t cap:in="media:disbound-page;textable";op=page_to_text;out="media:txt;textable"\n' +
+    'pages -> LOOP p2t -> texts'
+  );
+  assertEqual(g.edgeCount(), 1);
+  assertEqual(g.edges()[0].isLoop, true);
+}
+
+function testMachine_lineBasedFanIn() {
+  const g = Machine.fromString(
+    'thumb cap:in="media:pdf";op=generate_thumbnail;out="media:image;png;thumbnail"\n' +
+    'model_dl cap:in="media:model-spec;textable";op=download;out="media:model-spec;textable"\n' +
+    'describe cap:in="media:image;png";op=describe_image;out="media:image-description;textable"\n' +
+    'doc -> thumb -> thumbnail\n' +
+    'spec_input -> model_dl -> model_spec\n' +
+    '(thumbnail, model_spec) -> describe -> description'
+  );
+  assertEqual(g.edgeCount(), 3);
+  assertEqual(g.edges()[2].sources.length, 2);
+}
+
+function testMachine_mixedBracketedAndLineBased() {
+  const g = Machine.fromString(
+    '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]\n' +
+    'doc -> extract -> text'
+  );
+  assertEqual(g.edgeCount(), 1);
+}
+
+function testMachine_lineBasedEquivalentToBracketed() {
+  const g1 = Machine.fromString(
+    '[extract cap:in="media:pdf";op=extract;out="media:txt;textable"]' +
+    '[doc -> extract -> text]'
+  );
+  const g2 = Machine.fromString(
+    'extract cap:in="media:pdf";op=extract;out="media:txt;textable"\n' +
+    'doc -> extract -> text'
+  );
+  assert(g1.isEquivalent(g2), 'Line-based and bracketed must produce equivalent graphs');
+}
+
+function testMachine_lineBasedFormatSerialization() {
+  const g = new Machine([
+    new MachineEdge(
+      [MediaUrn.fromString('media:pdf')],
+      CapUrn.fromString('cap:in="media:pdf";op=extract;out="media:txt;textable"'),
+      MediaUrn.fromString('media:txt;textable'),
+      false
+    ),
+  ]);
+  const lineBased = g.toMachineNotationFormatted('line-based');
+  assert(!lineBased.includes('['), 'Line-based format must not contain brackets');
+  assert(!lineBased.includes(']'), 'Line-based format must not contain brackets');
+  assert(lineBased.includes('extract cap:'), 'Should contain header');
+  assert(lineBased.includes('-> extract ->'), 'Should contain wiring');
+
+  // Round-trip
+  const reparsed = Machine.fromString(lineBased);
+  assert(g.isEquivalent(reparsed), 'Line-based round-trip must produce equivalent graph');
+}
+
+function testMachine_lineBasedAndBracketedParseSameGraph() {
+  const g = new Machine([
+    new MachineEdge(
+      [MediaUrn.fromString('media:pdf')],
+      CapUrn.fromString('cap:in="media:pdf";op=extract;out="media:txt;textable"'),
+      MediaUrn.fromString('media:txt;textable'),
+      false
+    ),
+    new MachineEdge(
+      [MediaUrn.fromString('media:txt;textable')],
+      CapUrn.fromString('cap:in="media:txt;textable";op=embed;out="media:embedding-vector;record;textable"'),
+      MediaUrn.fromString('media:embedding-vector;record;textable'),
+      false
+    ),
+  ]);
+  const bracketed = g.toMachineNotationFormatted('bracketed');
+  const lineBased = g.toMachineNotationFormatted('line-based');
+
+  const gBracketed = Machine.fromString(bracketed);
+  const gLineBased = Machine.fromString(lineBased);
+  assert(gBracketed.isEquivalent(gLineBased),
+    'Bracketed and line-based must parse to equivalent graphs');
+}
+
 // --- Machine graph tests (mirrors graph.rs tests) ---
 
 function testMachine_edgeEquivalenceSameUrns() {
@@ -3719,6 +3910,9 @@ async function runTests() {
   runTest('JS: get_extension_mappings', testJS_getExtensionMappings);
   runTest('JS: cap_with_media_specs', testJS_capWithMediaSpecs);
   runTest('JS: cap_json_serialization', testJS_capJSONSerialization);
+  runTest('JS: cap_documentation_round_trip', testJS_capDocumentationRoundTrip);
+  runTest('JS: cap_documentation_omitted_when_null', testJS_capDocumentationOmittedWhenNull);
+  runTest('JS: media_spec_documentation_propagates_through_resolve', testJS_mediaSpecDocumentationPropagatesThroughResolve);
   runTest('JS: stdin_source_kind_constants', testJS_stdinSourceKindConstants);
   runTest('JS: stdin_source_null_data', testJS_stdinSourceNullData);
   const p1 = runTest('JS: args_passed_to_executeCap', testJS_argsPassedToExecuteCap);
@@ -3808,6 +4002,17 @@ async function runTests() {
   runTest('MACHINE:malformed_input_fails', testMachine_malformedInputFails);
   runTest('MACHINE:unterminated_bracket_fails', testMachine_unterminatedBracketFails);
 
+  // machine module: line-based mode tests
+  console.log('\n--- machine/parser.rs (line-based) ---');
+  runTest('MACHINE:line_based_simple_chain', testMachine_lineBasedSimpleChain);
+  runTest('MACHINE:line_based_two_step_chain', testMachine_lineBasedTwoStepChain);
+  runTest('MACHINE:line_based_loop', testMachine_lineBasedLoop);
+  runTest('MACHINE:line_based_fan_in', testMachine_lineBasedFanIn);
+  runTest('MACHINE:mixed_bracketed_and_line_based', testMachine_mixedBracketedAndLineBased);
+  runTest('MACHINE:line_based_equivalent_to_bracketed', testMachine_lineBasedEquivalentToBracketed);
+  runTest('MACHINE:line_based_format_serialization', testMachine_lineBasedFormatSerialization);
+  runTest('MACHINE:line_based_and_bracketed_parse_same_graph', testMachine_lineBasedAndBracketedParseSameGraph);
+
   // machine module: graph tests (mirrors graph.rs)
   console.log('\n--- machine/graph.rs ---');
   runTest('MACHINE:edge_equivalence_same_urns', testMachine_edgeEquivalenceSameUrns);

package/machine.pegjs

@@ -1,17 +1,26 @@
-// Bracket-delimited machine notation grammar for Peggy.
+// Machine notation grammar for Peggy.
 //
 // This grammar mirrors the Rust pest grammar in machine.pest exactly.
 // All actions return location() for LSP position tracking.
 //
-// Examples:
+// Two equally valid statement forms:
+//
+// Bracketed (one or more statements per line, any layout):
 //   [extract cap:in="media:pdf";op=extract;out="media:txt;textable"]
 //   [doc -> extract -> text]
-//   [(thumbnail, model_spec) -> describe -> description]
-//   [pages -> LOOP p2t -> texts]
+//
+// Line-based (one statement per line, no brackets):
+//   extract cap:in="media:pdf";op=extract;out="media:txt;textable"
+//   doc -> extract -> text
+//   (thumbnail, model_spec) -> describe -> description
+//   pages -> LOOP p2t -> texts
+//
+// Both forms can be freely mixed in the same program.
 
 program = _ stmts:stmt* _ { return stmts; }
 
 stmt = "[" _ inner:inner _ "]" _ { return inner; }
+     / inner:inner _ { return inner; }
 
 inner = wiring / header
 
@@ -48,11 +57,14 @@ alias = $( [a-zA-Z_] [a-zA-Z0-9_-]* )
 // Cap URN with location tracking
 cap_urn_loc = c:cap_urn { return { value: c, location: location() }; }
 
-// Cap URN: starts with "cap:", reads until the statement-closing "]",
-// except quoted strings can contain "]".
+// Cap URN: starts with "cap:", reads until a statement terminator:
+// "]" for bracketed mode, or newline for line-based mode.
+// Quoted strings can contain "]" and newlines.
 cap_urn = $( "cap:" cap_urn_body* )
 
-cap_urn_body = quoted_value / ( !"]" . )
+cap_urn_body = quoted_value / ( !"]" !NL . )
+
+NL "newline" = "\r\n" / "\n" / "\r"
 
 // Quoted strings support escaped quotes.
 quoted_value = '"' ( '\\"' / '\\\\' / (!'"' .) )* '"'

package/package.json

@@ -37,5 +37,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "0.100.226"
+  "version": "0.102.232"
 }