@principled/cairn 1.0.0-beta

package/dist/cli/commands/inspect.js

@@ -0,0 +1,153 @@
+import { Command } from 'commander';
+import { parseConfigOptions, buildCatalog } from '../helpers.js';
+import { isStale, getUnreviewedUpdates } from '../../provenance/staleness.js';
+export function inspectCommand() {
+    const cmd = new Command('inspect')
+        .description('Inspect a single element')
+        .argument('[element]', 'Element ID (optional with --ref)')
+        .option('--trace', 'Show ancestor trace (maps_to graph)')
+        .option('--descendants', 'Show descendant trace')
+        .option('--refs', 'Show refs with status')
+        .option('--reviews', 'Show review history')
+        .option('--updates', 'Show update history')
+        .option('--ref <file::id>', 'Find elements referencing a file/identifier and trace')
+        .option('--format <format>', 'Output format (text, json)', 'text')
+        .action(async (elementArg) => {
+        try {
+            const { config } = parseConfigOptions(cmd);
+            const catalog = buildCatalog(config);
+            const opts = cmd.opts();
+            // If no element and no --ref, show help
+            if (!elementArg && !opts.ref) {
+                cmd.help();
+                return;
+            }
+            // Handle --ref mode (DEC-10.7)
+            if (opts.ref) {
+                const refArg = opts.ref;
+                const parts = refArg.split('::');
+                const file = parts[0];
+                const identifier = parts.length > 1 ? parts[1] : undefined;
+                const matching = catalog.getAllElements().filter(e => {
+                    const refs = e.get('refs');
+                    if (!refs)
+                        return false;
+                    return refs.some(r => r.file === file && (!identifier || r.identifier === identifier));
+                });
+                if (matching.length === 0) {
+                    console.error(`No elements reference ${refArg}`);
+                    process.exit(0);
+                }
+                for (const el of matching) {
+                    console.error(`${el.toLibraryId()}  "${el.name}"  (${el.categoryName})`);
+                    if (opts.trace) {
+                        const graph = catalog.ancestors(el);
+                        for (const ancestor of graph.nodes.filter(n => n.hashKey() !== el.hashKey())) {
+                            console.error(`  → ${ancestor.toLibraryId()}  "${ancestor.name}"  (${ancestor.categoryName})`);
+                        }
+                    }
+                    console.error('');
+                }
+                process.exit(0);
+            }
+            // Find element
+            const element = catalog.getAllElements().find(e => e.id === elementArg ||
+                e.toLibraryId() === elementArg ||
+                e.hashKey() === elementArg);
+            if (!element) {
+                console.error(`Element '${elementArg}' not found`);
+                process.exit(1);
+            }
+            if (opts.format === 'json') {
+                const output = {
+                    ...element.data,
+                    _category: element.categoryName,
+                    _libraryId: element.toLibraryId(),
+                    _canonicalId: element.toCanonicalId(),
+                };
+                process.stdout.write(JSON.stringify(output, null, 2));
+                process.exit(0);
+            }
+            // Default text output
+            console.error(`${element.toLibraryId()}  "${element.name}"`);
+            console.error(`Category: ${element.categoryName}`);
+            console.error(`Status: ${element.status}`);
+            if (element.tags.length > 0)
+                console.error(`Tags: ${element.tags.join(', ')}`);
+            if (element.maps_to.length > 0)
+                console.error(`Maps to: ${element.maps_to.join(', ')}`);
+            if (element.priority !== undefined)
+                console.error(`Priority: ${element.priority}`);
+            // Primary field
+            const catDef = catalog.registry.getByName(element.categoryName);
+            const primaryField = catDef?.primary_field ?? 'statement';
+            const primaryValue = element.get(primaryField);
+            if (primaryValue)
+                console.error(`\n${String(primaryValue).trim()}`);
+            // Stale status
+            if (isStale(element)) {
+                const unreviewed = getUnreviewedUpdates(element);
+                console.error(`\n⚠ STALE: ${unreviewed.length} unreviewed update(s)`);
+            }
+            // --trace: show ancestor graph
+            if (opts.trace) {
+                console.error('\n--- Ancestor Trace ---');
+                const graph = catalog.ancestors(element);
+                for (const node of graph.nodes) {
+                    if (node.hashKey() === element.hashKey())
+                        continue;
+                    console.error(`  → ${node.toLibraryId()}  "${node.name}"  (${node.categoryName})`);
+                }
+            }
+            // --descendants
+            if (opts.descendants) {
+                console.error('\n--- Descendants ---');
+                const graph = catalog.descendants(element);
+                for (const node of graph.nodes) {
+                    if (node.hashKey() === element.hashKey())
+                        continue;
+                    console.error(`  ← ${node.toLibraryId()}  "${node.name}"  (${node.categoryName})`);
+                }
+            }
+            // --refs
+            if (opts.refs) {
+                const refs = element.get('refs');
+                if (refs && refs.length > 0) {
+                    console.error('\n--- Refs ---');
+                    for (const ref of refs) {
+                        console.error(`  ${ref.role}: ${ref.file}::${ref.identifier}`);
+                    }
+                }
+                else {
+                    console.error('\nNo refs.');
+                }
+            }
+            // --reviews
+            if (opts.reviews) {
+                const reviews = (element.get('reviewed_by') ?? []);
+                console.error(`\n--- Reviews (${reviews.length}) ---`);
+                for (const r of reviews) {
+                    console.error(`  ${r.date}  by: ${JSON.stringify(r.by ?? 'unknown')}  updates: ${JSON.stringify(r.updates_reviewed)}`);
+                    if (r.note)
+                        console.error(`    Note: ${r.note}`);
+                }
+            }
+            // --updates
+            if (opts.updates) {
+                const updates = (element.get('updated_by') ?? []);
+                console.error(`\n--- Updates (${updates.length}) ---`);
+                for (const u of updates) {
+                    const skip = u.skip_review ? ' [skip-review]' : '';
+                    console.error(`  ${u.date}  "${u.rationale}"${skip}`);
+                }
+            }
+            console.error('');
+        }
+        catch (e) {
+            console.error(`Error: ${e.message}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=inspect.js.map

package/dist/cli/commands/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../../src/cli/commands/inspect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE9E,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,SAAS,CAAC;SAC/B,WAAW,CAAC,0BAA0B,CAAC;SACvC,QAAQ,CAAC,WAAW,EAAE,kCAAkC,CAAC;SACzD,MAAM,CAAC,SAAS,EAAE,qCAAqC,CAAC;SACxD,MAAM,CAAC,eAAe,EAAE,uBAAuB,CAAC;SAChD,MAAM,CAAC,QAAQ,EAAE,uBAAuB,CAAC;SACzC,MAAM,CAAC,WAAW,EAAE,qBAAqB,CAAC;SAC1C,MAAM,CAAC,WAAW,EAAE,qBAAqB,CAAC;SAC1C,MAAM,CAAC,kBAAkB,EAAE,uDAAuD,CAAC;SACnF,MAAM,CAAC,mBAAmB,EAAE,4BAA4B,EAAE,MAAM,CAAC;SACjE,MAAM,CAAC,KAAK,EAAE,UAA8B,EAAE,EAAE;QAC/C,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;YACrC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;YAExB,wCAAwC;YACxC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC7B,GAAG,CAAC,IAAI,EAAE,CAAC;gBACX,OAAO;YACT,CAAC;YAED,+BAA+B;YAC/B,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBACb,MAAM,MAAM,GAAG,IAAI,CAAC,GAAa,CAAC;gBAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACjC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACtB,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBAE3D,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;oBACnD,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAA0D,CAAC;oBACpF,IAAI,CAAC,IAAI;wBAAE,OAAO,KAAK,CAAC;oBACxB,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CACnB,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,KAAK,UAAU,CAAC,CAChE,CAAC;gBACJ,CAAC,CAAC,CAAC;gBAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,OAAO,CAAC,KAAK,CAAC,yBAAyB,MAAM,EAAE,CAAC,CAAC;oBACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,CAAC;gBAED,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;oBAC1B,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC,YAAY,GAAG,CAAC,CAAC;oBACzE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;wBACf,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;wBACpC,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;4BAC7E,OAAO,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,WAAW,EAAE,MAAM,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,YAAY,GAAG,CAAC,CAAC;wBACjG,CAAC;oBACH,CAAC;oBACD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACpB,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YAED,eAAe;YACf,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAChD,CAAC,CAAC,EAAE,KAAK,UAAU;gBACnB,CAAC,CAAC,WAAW,EAAE,KAAK,UAAU;gBAC9B,CAAC,CAAC,OAAO,EAAE,KAAK,UAAU,CAC3B,CAAC;YAEF,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,YAAY,UAAU,aAAa,CAAC,CAAC;gBACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YAED,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC3B,MAAM,MAAM,GAA4B;oBACtC,GAAG,OAAO,CAAC,IAAI;oBACf,SAAS,EAAE,OAAO,CAAC,YAAY;oBAC/B,UAAU,EAAE,OAAO,CAAC,WAAW,EAAE;oBACjC,YAAY,EAAE,OAAO,CAAC,aAAa,EAAE;iBACtC,CAAC;gBACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;gBACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YAED,sBAAsB;YACtB,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;YAC7D,OAAO,CAAC,KAAK,CAAC,aAAa,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;YACnD,OAAO,CAAC,KAAK,CAAC,WAAW,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAC3C,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,CAAC,KAAK,CAAC,SAAS,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/E,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,CAAC,KAAK,CAAC,YAAY,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxF,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;gBAAE,OAAO,CAAC,KAAK,CAAC,aAAa,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;YAEnF,gBAAgB;YAChB,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAChE,MAAM,YAAY,GAAG,MAAM,EAAE,aAAa,IAAI,WAAW,CAAC;YAC1D,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAC/C,IAAI,YAAY;gBAAE,OAAO,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAEpE,eAAe;YACf,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrB,MAAM,UAAU,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;gBACjD,OAAO,CAAC,KAAK,CAAC,cAAc,UAAU,CAAC,MAAM,uBAAuB,CAAC,CAAC;YACxE,CAAC;YAED,+BAA+B;YAC/B,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;gBAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;gBACzC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;oBAC/B,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE;wBAAE,SAAS;oBACnD,OAAO,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;gBACrF,CAAC;YACH,CAAC;YAED,gBAAgB;YAChB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrB,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;gBACvC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;gBAC3C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;oBAC/B,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE;wBAAE,SAAS;oBACnD,OAAO,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;gBACrF,CAAC;YACH,CAAC;YAED,SAAS;YACT,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAwE,CAAC;gBACxG,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC5B,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;oBAChC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;wBACvB,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;oBACjE,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC;YAED,YAAY;YACZ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAmC,CAAC;gBACrF,OAAO,CAAC,KAAK,CAAC,kBAAkB,OAAO,CAAC,MAAM,OAAO,CAAC,CAAC;gBACvD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;oBACxB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,SAAS,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;oBACvH,IAAI,CAAC,CAAC,IAAI;wBAAE,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBACnD,CAAC;YACH,CAAC;YAED,YAAY;YACZ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAmC,CAAC;gBACpF,OAAO,CAAC,KAAK,CAAC,kBAAkB,OAAO,CAAC,MAAM,OAAO,CAAC,CAAC;gBACvD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;oBACxB,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC;gBACxD,CAAC;YACH,CAAC;YAED,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,UAAW,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;YAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cli/commands/query.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function queryCommand(): Command;
+//# sourceMappingURL=query.d.ts.map

package/dist/cli/commands/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,YAAY,IAAI,OAAO,CAmFtC"}

package/dist/cli/commands/query.js

@@ -0,0 +1,77 @@
+import { Command } from 'commander';
+import { parseConfigOptions, buildCatalog } from '../helpers.js';
+export function queryCommand() {
+    const cmd = new Command('query')
+        .description('Query and filter elements in the catalog')
+        .option('-c, --category <name>', 'Filter by category')
+        .option('-t, --tag <tag>', 'Filter by tag')
+        .option('-s, --status <status>', 'Filter by status (default: active)', 'active')
+        .option('-d, --document <name>', 'Filter by document')
+        .option('--refs-file <path>', 'Filter by ref file path (DEC-10.6)')
+        .option('--refs-identifier <id>', 'Filter by ref identifier (DEC-10.6)')
+        .option('--format <format>', 'Output format (text, json, csv)', 'text')
+        .option('--include-deprecated', 'Include deprecated/rejected elements')
+        .action(async () => {
+        try {
+            const { config } = parseConfigOptions(cmd);
+            const catalog = buildCatalog(config);
+            const opts = cmd.opts();
+            let elements = catalog.getAllElements();
+            // Apply filters
+            if (!opts.includeDeprecated) {
+                const status = opts.status;
+                elements = elements.filter(e => e.status === status);
+            }
+            if (opts.category) {
+                elements = elements.filter(e => e.categoryName === opts.category);
+            }
+            if (opts.tag) {
+                elements = elements.filter(e => e.tags.includes(opts.tag));
+            }
+            if (opts.document) {
+                elements = elements.filter(e => e.documentPath === opts.document || e.documentPath.includes(opts.document));
+            }
+            // Ref filters (DEC-10.6)
+            if (opts.refsFile || opts.refsIdentifier) {
+                elements = elements.filter(e => {
+                    const refs = e.get('refs');
+                    if (!refs)
+                        return false;
+                    return refs.some(r => (!opts.refsFile || r.file === opts.refsFile) &&
+                        (!opts.refsIdentifier || r.identifier === opts.refsIdentifier));
+                });
+            }
+            if (opts.format === 'json') {
+                const output = elements.map(e => ({
+                    ...e.data,
+                    _category: e.categoryName,
+                    _libraryId: e.toLibraryId(),
+                    _canonicalId: e.toCanonicalId(),
+                }));
+                process.stdout.write(JSON.stringify(output, null, 2));
+            }
+            else if (opts.format === 'csv') {
+                const header = 'qualified_id,category,name,status,tags';
+                const rows = elements.map(e => `${e.toLibraryId()},${e.categoryName},"${e.name}",${e.status},"${e.tags.join(';')}"`);
+                process.stdout.write([header, ...rows].join('\n'));
+            }
+            else {
+                // Text output
+                if (elements.length === 0) {
+                    console.error('No elements match the query.');
+                    process.exit(0);
+                }
+                console.error(`Found ${elements.length} element(s):\n`);
+                for (const el of elements) {
+                    console.error(`  ${el.toLibraryId()}  "${el.name}"  [${el.categoryName}]  tags: [${el.tags.join(', ')}]`);
+                }
+            }
+        }
+        catch (e) {
+            console.error(`Error: ${e.message}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=query.js.map

package/dist/cli/commands/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/cli/commands/query.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/review.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function reviewCommand(): Command;
+//# sourceMappingURL=review.d.ts.map

package/dist/cli/commands/review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/review.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,aAAa,IAAI,OAAO,CAgIvC"}

package/dist/cli/commands/review.js

@@ -0,0 +1,118 @@
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import { randomUUID } from 'crypto';
+import { parseConfigOptions, buildCatalog, requireUserIdentity } from '../helpers.js';
+import { isStale, getUnreviewedUpdates } from '../../provenance/staleness.js';
+import { computeReviewHash, validateReviewHash } from '../../provenance/review-hash.js';
+export function reviewCommand() {
+    const cmd = new Command('review')
+        .description('Review stale elements and stamp reviewed_by')
+        .argument('[element]', 'Element qualified ID to review (e.g., gvp:P1)')
+        .option('--approve', 'Approve with review hash token (hidden)')
+        .option('--token <hash>', 'Review hash token from gvp review output')
+        .option('--note <text>', 'Review note')
+        .option('--by <name>', 'Reviewer name (overrides config)')
+        .action(async (elementId) => {
+        try {
+            const { config } = parseConfigOptions(cmd);
+            const catalog = buildCatalog(config);
+            const opts = cmd.opts();
+            if (!elementId) {
+                // List all stale elements
+                const staleElements = catalog.getAllElements().filter(e => e.status === 'active' && isStale(e));
+                if (staleElements.length === 0) {
+                    console.error('No stale elements found. All reviews are up to date.');
+                    process.exit(0);
+                }
+                console.error(`Found ${staleElements.length} stale element(s):\n`);
+                for (const el of staleElements) {
+                    const unreviewedIds = getUnreviewedUpdates(el);
+                    console.error(`  ${el.toLibraryId()}  "${el.name}"  (${unreviewedIds.length} unreviewed update(s))`);
+                }
+                process.exit(0);
+            }
+            // Find the specific element
+            const element = catalog.getAllElements().find(e => e.toLibraryId() === elementId || e.hashKey() === elementId || e.id === elementId);
+            if (!element) {
+                console.error(`Element '${elementId}' not found`);
+                process.exit(1);
+            }
+            const unreviewedIds = getUnreviewedUpdates(element);
+            if (opts.approve) {
+                // --approve mode: validate hash token (DEC-4.5)
+                if (!opts.token) {
+                    console.error('--approve requires --token <hash>. Run `cairn review <element>` first to get the hash.');
+                    process.exit(1);
+                }
+                if (!validateReviewHash(opts.token, unreviewedIds)) {
+                    console.error('Invalid review token. The element may have been updated since you last reviewed it.');
+                    console.error('Run `cairn review ' + elementId + '` again to get a fresh token.');
+                    process.exit(1);
+                }
+                // Stamp reviewed_by
+                const user = requireUserIdentity(config);
+                const reviewEntry = {
+                    id: randomUUID(),
+                    date: new Date().toISOString(),
+                    by: user,
+                    updates_reviewed: unreviewedIds,
+                    note: opts.note ?? undefined,
+                };
+                // Find and update the YAML file
+                const doc = catalog.documents.find(d => d.getAllElements().some(e => e.hashKey() === element.hashKey()));
+                if (!doc) {
+                    console.error('Could not find document containing this element');
+                    process.exit(1);
+                }
+                const content = fs.readFileSync(doc.filePath, 'utf-8');
+                const data = yaml.load(content);
+                const catDef = catalog.registry.getByName(element.categoryName);
+                if (!catDef) {
+                    console.error('Category not found');
+                    process.exit(1);
+                }
+                const items = data[catDef.yaml_key];
+                const target = items?.find(item => item.id === element.id);
+                if (!target) {
+                    console.error('Element not found in YAML');
+                    process.exit(1);
+                }
+                if (!target.reviewed_by)
+                    target.reviewed_by = [];
+                target.reviewed_by.push(reviewEntry);
+                fs.writeFileSync(doc.filePath, yaml.dump(data, {
+                    lineWidth: -1, noRefs: true, sortKeys: false,
+                }));
+                console.error(`Reviewed ${element.toLibraryId()} — ${unreviewedIds.length} update(s) marked as reviewed.`);
+                process.exit(0);
+            }
+            // Default: show element details and review hash
+            console.error(`Element: ${element.toLibraryId()}  "${element.name}"`);
+            console.error(`Category: ${element.categoryName}`);
+            console.error(`Status: ${element.status}`);
+            console.error('');
+            if (unreviewedIds.length === 0) {
+                console.error('This element has no unreviewed updates.');
+                process.exit(0);
+            }
+            console.error(`Unreviewed updates: ${unreviewedIds.length}`);
+            for (const uid of unreviewedIds) {
+                console.error(`  - ${uid}`);
+            }
+            console.error('');
+            // Output the review hash (DEC-4.5: discoverable at end of review output)
+            const hash = computeReviewHash(unreviewedIds);
+            console.error(`To approve this review:`);
+            console.error(`  gvp review ${elementId} --approve --token ${hash}`);
+        }
+        catch (e) {
+            console.error(`Error: ${e.message}`);
+            process.exit(1);
+        }
+    });
+    // Hide --approve from help (DEC-4.5)
+    cmd.options.find(o => o.long === '--approve').hidden = true;
+    return cmd;
+}
+//# sourceMappingURL=review.js.map

package/dist/cli/commands/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../../src/cli/commands/review.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/validate.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function validateCommand(): Command;
+//# sourceMappingURL=validate.d.ts.map

package/dist/cli/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6EpC,wBAAgB,eAAe,IAAI,OAAO,CAwDzC"}

package/dist/cli/commands/validate.js

@@ -0,0 +1,125 @@
+import { Command } from 'commander';
+import { execSync } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+import { parseConfigOptions, buildCatalog } from '../helpers.js';
+import { runValidation, hasErrors, builtinPasses, optionalPasses } from '../../validation/index.js';
+/**
+ * Find the git root by walking up from cwd.
+ */
+function findGitRoot(cwd) {
+    let current = path.resolve(cwd);
+    while (true) {
+        if (fs.existsSync(path.join(current, '.git'))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Get changed files for a given scope.
+ */
+function getChangedFiles(scope, cwd) {
+    const gitRoot = findGitRoot(cwd);
+    if (!gitRoot)
+        return [];
+    let gitCmd;
+    if (scope === 'staged') {
+        gitCmd = 'git diff --cached --name-only';
+    }
+    else if (scope === 'working') {
+        gitCmd = 'git diff --name-only';
+    }
+    else if (scope.includes('..')) {
+        // Commit range
+        gitCmd = `git diff --name-only ${scope}`;
+    }
+    else {
+        return [];
+    }
+    try {
+        const output = execSync(gitCmd, { cwd: gitRoot, encoding: 'utf-8' });
+        return output.trim().split('\n').filter(f => f.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check if a diagnostic is related to a set of changed files.
+ * Ref-related diagnostics (W010, W011, W012) are filtered by ref file.
+ * Element-related diagnostics are filtered by whether the element has refs pointing to changed files.
+ * Structural/traceability diagnostics always pass through (not file-scoped).
+ */
+function isDiagnosticInScope(d, changedSet) {
+    // Ref-specific diagnostics: filter by the ref file path
+    if (d.code === 'W010' || d.code === 'W011' || d.code === 'W012') {
+        return d.context.details !== undefined && changedSet.has(d.context.details.split('::')[0]);
+    }
+    // Structural and traceability passes are not file-scoped — always include
+    if (d.pass === 'schema' || d.pass === 'structural' || d.pass === 'traceability') {
+        return true;
+    }
+    // For other element-related diagnostics with a details field containing a file path,
+    // check if it's in the changed set
+    if (d.context.details && changedSet.has(d.context.details)) {
+        return true;
+    }
+    // Default: include (non-file-scoped diagnostics like W001, W002, W005, W006)
+    return true;
+}
+export function validateCommand() {
+    const cmd = new Command('validate')
+        .description('Validate the GVP library')
+        .option('--scope <scope>', 'Scope validation to: staged, working, or <commit>..<commit> (DEC-10.5)')
+        .option('--coverage', 'Enable the coverage pass (W012, W013)')
+        .option('--passes <passes>', 'Comma-separated list of passes to run (e.g., schema,structural,semantic,coverage)')
+        .action(async () => {
+        try {
+            const { config } = parseConfigOptions(cmd);
+            const catalog = buildCatalog(config);
+            const opts = cmd.opts();
+            // Build the passes map
+            const allPasses = new Map([...builtinPasses, ...optionalPasses]);
+            // Determine which pass names to run
+            let passNames;
+            if (opts.passes) {
+                passNames = opts.passes.split(',').map(s => s.trim());
+            }
+            else if (opts.coverage) {
+                // Add coverage to the default passes
+                passNames = [...builtinPasses.keys(), 'coverage'];
+            }
+            const diagnostics = runValidation(catalog, config, allPasses, passNames);
+            // Apply scope filtering if --scope is provided
+            let filteredDiagnostics = diagnostics;
+            if (opts.scope) {
+                const changedFiles = getChangedFiles(opts.scope, process.cwd());
+                const changedSet = new Set(changedFiles);
+                filteredDiagnostics = diagnostics.filter(d => isDiagnosticInScope(d, changedSet));
+            }
+            // Print diagnostics to stderr (DEC-5.12)
+            for (const d of filteredDiagnostics) {
+                const prefix = d.severity === 'error' ? 'ERROR' : 'WARN';
+                const location = d.context.elementId
+                    ? `${d.context.documentPath ?? ''}:${d.context.elementId}`
+                    : d.context.documentPath ?? '';
+                console.error(`${prefix}  ${d.code}  ${location}  ${d.description}`);
+            }
+            if (filteredDiagnostics.length === 0) {
+                console.error('Validation passed. Structural checks OK. Use `cairn export` for semantic review.');
+            }
+            // Exit code (DEC-5.12): 0 for success/warnings, non-zero for errors
+            process.exit(hasErrors(filteredDiagnostics) ? 1 : 0);
+        }
+        catch (e) {
+            console.error(`Error: ${e.message}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=validate.js.map

package/dist/cli/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/cli/commands/validate.ts"],"names":[],"mappings":"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"}

package/dist/cli/helpers.d.ts

@@ -0,0 +1,24 @@
+import { type LoadConfigOptions } from '../config/loader.js';
+import type { GVPConfig } from '../config/schema.js';
+import { Catalog } from '../catalog/catalog.js';
+import type { Command } from 'commander';
+/**
+ * Parse global options from a Commander command into LoadConfigOptions.
+ */
+export declare function parseConfigOptions(cmd: Command): {
+    config: GVPConfig;
+    configOptions: LoadConfigOptions;
+};
+/**
+ * Build a Catalog from the current working directory.
+ */
+export declare function buildCatalog(config: GVPConfig, cwd?: string): Catalog;
+/**
+ * Require user identity for provenance operations (DEC-4.3, DEC-4.8).
+ * Exits with an error if user identity is not configured.
+ */
+export declare function requireUserIdentity(config: GVPConfig): {
+    name: string;
+    email: string;
+};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/cli/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/cli/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,aAAa,EAAE,iBAAiB,CAAA;CAAE,CA8BxG;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,GAAE,MAAsB,GAAG,OAAO,CAsFpF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAYtF"}