patram 0.10.0 → 0.12.0

package/lib/cli/help-metadata.js

@@ -87,14 +87,15 @@ const COMMAND_DEFINITIONS = {
       'patram check',
       'patram check docs',
       'patram check docs/patram.md',
+      'patram check docs docs/patram.md',
     ],
-    extra_positionals_message: 'Check accepts at most one path.',
+    extra_positionals_message: 'Check accepts zero or more paths.',
     help_topics: [],
-    max_positionals: 1,
+    max_positionals: Number.POSITIVE_INFINITY,
     min_positionals: 0,
     missing_argument_examples: [],
     missing_argument_label: null,
-    missing_usage_lines: ['patram check [path]'],
+    missing_usage_lines: ['patram check [path ...]'],
     option_column_width: 10,
     options: [
       {
@@ -110,7 +111,7 @@ const COMMAND_DEFINITIONS = {
     root_summary: 'Validate a project, directory, or file',
     summary:
       'Validate a project, directory, or file and report graph diagnostics.',
-    usage_lines: ['patram check [path] [options]'],
+    usage_lines: ['patram check [path ...] [options]'],
   },
   fields: {
     allowed_option_names: new Set(),
@@ -141,41 +142,42 @@ const COMMAND_DEFINITIONS = {
   },
   query: {
     allowed_option_names: new Set([
+      'cypher',
       'explain',
       'limit',
       'lint',
       'offset',
-      'where',
     ]),
     examples: [
       'patram query active-plans',
-      "patram query --where 'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md'",
-      "patram query --where 'status not in [done, dropped, superseded]'",
-      "patram query --where '$class=plan and none(in:tracked_in, $class=decision)'",
-      "patram query --where 'count(in:decided_by, $class=task) = 0'",
+      'patram query --cypher "MATCH (n:Plan) WHERE n.status = \'active\' RETURN n"',
+      'patram query --cypher "MATCH (n) WHERE id(n) = \'plan:v0/worktracking-agent-guidance\' RETURN n"',
+      "patram query --cypher \"MATCH (n) WHERE n.status NOT IN ['done', 'dropped', 'superseded'] RETURN n\"",
+      'patram query --cypher "MATCH (n:Plan) WHERE NOT EXISTS { MATCH (decision:Decision)-[:TRACKED_IN]->(n) } RETURN n"',
+      'patram query --cypher "MATCH (n:Decision) WHERE COUNT { MATCH (task:Task)-[:DECIDED_BY]->(n) } = 0 RETURN n"',
       'patram query ready-tasks --explain',
-      "patram query --where '$class=decision and status=accepted and count(in:decided_by, $class=task) = 0' --lint",
+      'patram query --cypher "MATCH (n:Decision) WHERE n.status = \'accepted\' AND COUNT { MATCH (task:Task)-[:DECIDED_BY]->(n) } = 0 RETURN n" --lint',
       'patram query active-plans --limit 10 --offset 20',
     ],
     extra_positionals_message:
-      'Query accepts either "--where" or a stored query name.',
+      'Query accepts "--cypher" or a stored query name.',
     help_topics: ['query-language'],
     max_positionals: 1,
     min_positionals: 0,
     missing_argument_examples: [
       'patram query active-plans',
-      "patram query --where 'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md'",
+      'patram query --cypher "MATCH (n:Plan) WHERE n.status = \'active\' RETURN n"',
     ],
-    missing_argument_label: "<name> or --where '<clause>'",
+    missing_argument_label: "<name> or --cypher '<query>'",
     missing_usage_lines: [
       'patram query <name> [options]',
-      "patram query --where '<clause>' [options]",
+      `patram query --cypher '<query>' [options]`,
     ],
     option_column_width: 19,
     options: [
       {
-        description: 'Run an ad hoc query instead of a stored query',
-        label: '--where <clause>',
+        description: 'Run an ad hoc Cypher query instead of a stored query',
+        label: '--cypher <query>',
       },
       {
         description: 'Skip the first N matches',
@@ -203,35 +205,57 @@ const COMMAND_DEFINITIONS = {
       },
     ],
     related: ['queries', 'show'],
-    root_summary: 'Run a stored query or an ad hoc where clause',
+    root_summary: 'Run a stored query or an ad hoc Cypher query',
     summary:
-      'Run a stored query or an ad hoc where clause against graph nodes.',
+      'Run a stored query or an ad hoc Cypher query against graph nodes.',
     syntax_lines: [
-      '$id=<value> | $class=<value> | $path=<value> | status=<value>',
-      '$id^=<prefix> | $path^=<prefix> | title~<text>',
-      '<field> in [<value>, ...] | <field> not in [<value>, ...]',
-      '<relation>:* | <relation>=<target-id>',
-      'any(<traversal>, <term> and <term>)',
-      'none(<traversal>, <term> and <term>)',
-      'count(<traversal>, <term> and <term>) <comparison> <number>',
+      'MATCH (n) RETURN n',
+      "MATCH (n:Label) WHERE n.status = 'active' RETURN n",
+      "MATCH (n) WHERE id(n) = 'command:query' RETURN n",
+      'MATCH (n) WHERE EXISTS { MATCH ... } RETURN n',
+      'MATCH (n) WHERE COUNT { MATCH ... } = 0 RETURN n',
     ],
     usage_lines: [
       'patram query <name> [options]',
-      "patram query --where '<clause>' [options]",
+      `patram query --cypher '<query>' [options]`,
     ],
   },
   queries: {
-    allowed_option_names: new Set(),
-    examples: ['patram queries'],
-    extra_positionals_message: 'Queries does not accept positional arguments.',
+    allowed_option_names: new Set(['cypher', 'desc', 'name']),
+    examples: [
+      'patram queries',
+      `patram queries add active-plans --cypher "MATCH (n:Plan) WHERE n.status = 'active' RETURN n"`,
+      "patram queries update ready-tasks --desc 'Show tasks that are ready.'",
+      `patram queries update ready-tasks --cypher "MATCH (n:Task) WHERE n.status = 'ready' RETURN n"`,
+      'patram queries remove ready-tasks',
+    ],
+    extra_positionals_message:
+      'Queries accepts no positionals unless using add, update, or remove.',
     help_topics: [],
-    max_positionals: 0,
+    max_positionals: 2,
     min_positionals: 0,
     missing_argument_examples: [],
     missing_argument_label: null,
-    missing_usage_lines: ['patram queries'],
-    option_column_width: 10,
+    missing_usage_lines: [
+      'patram queries',
+      'patram queries add <name> --cypher <query>',
+      'patram queries update <name> [--name <new_name>] [--cypher <query>] [--desc <text>]',
+      'patram queries remove <name>',
+    ],
+    option_column_width: 19,
     options: [
+      {
+        description: 'Persist a new stored Cypher query',
+        label: '--cypher <query>',
+      },
+      {
+        description: 'Set or rename the stored query name for update',
+        label: '--name <new_name>',
+      },
+      {
+        description: 'Set or clear the stored query description',
+        label: '--desc <text>',
+      },
       {
         description: 'Print plain text output',
         label: '--plain',
@@ -242,15 +266,21 @@ const COMMAND_DEFINITIONS = {
       },
     ],
     related: ['query'],
-    root_summary: 'List stored queries',
-    summary: 'List the stored queries defined in the project configuration.',
-    usage_lines: ['patram queries [options]'],
+    root_summary: 'List and manage stored queries',
+    summary:
+      'List stored queries or mutate them through add, update, and remove.',
+    usage_lines: [
+      'patram queries [options]',
+      `patram queries add <name> --cypher <query> [--desc <text>] [options]`,
+      'patram queries update <name> [--name <new_name>] [--cypher <query>] [--desc <text>] [options]',
+      'patram queries remove <name> [options]',
+    ],
   },
   refs: {
-    allowed_option_names: new Set(['where']),
+    allowed_option_names: new Set(['cypher']),
     examples: [
       'patram refs docs/decisions/query-language.md',
-      "patram refs docs/decisions/query-language.md --where '$class=document'",
+      'patram refs docs/decisions/query-language.md --cypher "MATCH (n:Document) RETURN n"',
       'patram refs docs/decisions/query-language.md --json',
     ],
     extra_positionals_message: 'Refs accepts exactly one file path.',
@@ -259,15 +289,15 @@ const COMMAND_DEFINITIONS = {
     min_positionals: 1,
     missing_argument_examples: [
       'patram refs docs/decisions/query-language.md',
-      "patram refs docs/patram.md --where '$class=document'",
+      'patram refs docs/patram.md --cypher "MATCH (n:Document) RETURN n"',
     ],
     missing_argument_label: '<file>',
     missing_usage_lines: ['patram refs <file>'],
     option_column_width: 19,
     options: [
       {
-        description: 'Filter incoming source nodes with a where clause',
-        label: '--where <clause>',
+        description: 'Filter incoming source nodes with a Cypher query',
+        label: '--cypher <query>',
       },
       {
         description: 'Print plain text output',
@@ -320,102 +350,67 @@ const COMMAND_DEFINITIONS = {
 const HELP_TOPIC_DEFINITIONS = {
   'query-language': {
     examples: [
-      '$class=decision and status=accepted',
-      '$class=task or status=done',
-      '($class=task or status=blocked) and title~Show',
-      '$path^=docs/plans/',
-      'title~query',
-      'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md',
-      'implements_command=command:query',
-      'status not in [done, dropped, superseded]',
-      'any(in:tracked_in, $class=task and status in [pending, ready, in_progress, blocked])',
-      'none(in:tracked_in, $class=decision)',
-      'count(in:decided_by, $class=task) = 0',
-      'not uses_term=term:graph',
+      "MATCH (n:Decision) WHERE n.status = 'accepted' RETURN n",
+      "MATCH (n:Task) WHERE n.status IN ['pending', 'ready'] RETURN n",
+      "MATCH (n) WHERE path(n) ENDS WITH '/README.md' RETURN n",
+      'MATCH (n:Plan) WHERE NOT EXISTS { MATCH (decision:Decision)-[:TRACKED_IN]->(n) } RETURN n',
+      'MATCH (n:Decision) WHERE COUNT { MATCH (task:Task)-[:DECIDED_BY]->(n) } = 0 RETURN n',
+      "MATCH (n) WHERE EXISTS { MATCH (n)-[:IMPLEMENTS_COMMAND]->(command:Command) WHERE id(command) = 'command:query' } RETURN n",
     ],
-    lead: 'Query language filters graph nodes with field, relation, traversal, and aggregate terms.',
+    lead: 'Query language uses a constrained Cypher subset for graph node selection.',
     operators: [
       {
-        description: 'Exact field match or exact count comparison',
-        label: '=',
-      },
-      {
-        description: 'Prefix match for structural id and path',
-        label: '^=',
-      },
-      {
-        description: 'Contains text for title',
-        label: '~',
-      },
-      {
-        description: 'Set membership for supported fields',
-        label: 'in',
+        description: 'Equality and exact value comparison',
+        label: '= | <>',
       },
       {
-        description: 'Set exclusion for supported fields',
-        label: 'not in',
+        description: 'String prefix, suffix, and contains checks',
+        label: 'STARTS WITH | ENDS WITH | CONTAINS',
       },
       {
-        description: 'Negate one term',
-        label: 'not',
+        description: 'Set membership checks',
+        label: 'IN | NOT IN',
       },
       {
-        description: 'Combine terms',
-        label: 'and',
+        description: 'Boolean composition',
+        label: 'AND | OR | NOT',
       },
       {
-        description: 'Match either side',
-        label: 'or',
+        description: 'Relation existence subqueries',
+        label: 'EXISTS { ... }',
       },
       {
-        description: 'Group boolean expressions',
-        label: '( )',
-      },
-      {
-        description: 'Count comparisons',
-        label: '!= < > >= <=',
+        description: 'Related-node count comparisons',
+        label: 'COUNT { ... }',
       },
     ],
     relation_terms: [
       {
-        description: 'Match nodes with at least one outgoing relation',
-        label: '<relation>:*',
-      },
-      {
-        description: 'Match nodes linked to an exact target id',
-        label: '<relation>=<target-id>',
+        description: 'Outgoing relation match',
+        label: '(n)-[:RELATION]->(target)',
       },
       {
-        description: 'Traverse one incoming relation hop',
-        label: 'in:<relation>',
+        description: 'Incoming relation match',
+        label: '(source)-[:RELATION]->(n)',
       },
       {
-        description: 'Traverse one outgoing relation hop',
-        label: 'out:<relation>',
+        description: 'Label-qualified related node pattern',
+        label: '(n)-[:RELATION]->(target:Label)',
       },
     ],
     terms: [
-      'Exact match: $id, $class, $path, status',
-      'Prefix match: $id, $path',
-      'Contains text: title',
-      'Set membership: $id, $class, $path, status, title',
+      'Root match: MATCH (n) or MATCH (n:Label)',
+      'Return shape: RETURN n',
+      'Structural functions: id(n), path(n)',
+      'Labels select class membership: MATCH (n:Label)',
+      'Common fields: n.title, n.status, n.kind',
+      'Subqueries: EXISTS { MATCH ... WHERE ... } and COUNT { MATCH ... WHERE ... }',
     ],
     usage_lines: [
-      '<field>=<value>',
-      '$id^=<prefix>',
-      '$path^=<prefix>',
-      'title~<text>',
-      '<field> in [<value>, ...]',
-      '<field> not in [<value>, ...]',
-      '<relation>:*',
-      '<relation>=<target-id>',
-      'any(<traversal>, <term> and <term>)',
-      'none(<traversal>, <term> and <term>)',
-      'count(<traversal>, <term> and <term>) <comparison> <number>',
-      'not <term>',
-      '<term> and <term>',
-      '<term> or <term>',
-      '(<expression>)',
+      'MATCH (n) RETURN n',
+      'MATCH (n:Label) WHERE <predicate> RETURN n',
+      'MATCH (n) WHERE EXISTS { MATCH ... } RETURN n',
+      'MATCH (n) WHERE COUNT { MATCH ... } <comparison> <number> RETURN n',
     ],
   },
 };
@@ -529,7 +524,7 @@ function listOptionLabels(command_name) {
   } else {
     option_labels.add('--limit');
     option_labels.add('--offset');
-    option_labels.add('--where');
+    option_labels.add('--cypher');
   }
 
   return [...option_labels];

package/lib/cli/main.js

@@ -16,16 +16,16 @@ import { runShowCommand } from './commands/show.js';
  * Loads repo state and routes `check`, `fields`, `query`, `queries`, and
  * `show` through the shared output pipeline.
  *
- * Kind: cli
- * Status: active
- * Implements Command: ../../docs/reference/commands/check.md
- * Implements Command: ../../docs/reference/commands/query.md
- * Implements Command: ../../docs/reference/commands/queries.md
- * Implements Command: ../../docs/reference/commands/refs.md
- * Implements Command: ../../docs/reference/commands/show.md
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../docs/decisions/cli-output-architecture.md
- * Decided by: ../../docs/decisions/cli-argument-parser.md
+ * kind: cli
+ * status: active
+ * implements_command: ../../docs/reference/commands/check.md
+ * implements_command: ../../docs/reference/commands/query.md
+ * implements_command: ../../docs/reference/commands/queries.md
+ * implements_command: ../../docs/reference/commands/refs.md
+ * implements_command: ../../docs/reference/commands/show.md
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../docs/decisions/cli-output-architecture.md
+ * decided_by: ../../docs/decisions/cli-argument-parser.md
  * @patram
  * @see {@link ./parse-arguments.js}
  * @see {@link ./commands/query.js}