@pithyjs/codex 0.1.0-beta.0

package/dist/annotations.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.annotations",
+ *   "title": "Codex Annotations",
+ *   "category": "feature"
+ * }
+ *
+ * Parses @codex and @codexApi annotations from source files to discover
+ * components and APIs. Provides content normalization and fingerprinting
+ * for change detection.
+ */
+import type { RiskLevel, TestingRequirements } from './extraction/types.js';
+/**
+ * Component/Feature annotation format
+ */
+export interface CodexAnnotation {
+    id: string;
+    title: string;
+    category: 'feature' | 'directive' | 'runtime' | 'compiler' | 'plugin' | 'types';
+    /** Risk level — affects testing requirements via pyramid modifiers */
+    risk?: RiskLevel;
+    /** Explicit testing requirements (overrides category defaults) */
+    testing?: TestingRequirements;
+}
+/**
+ * Public API annotation format
+ */
+export interface CodexApiAnnotation {
+    parent: string;
+    name: string;
+    stability?: 'internal' | 'experimental' | 'stable' | 'deprecated';
+    signature?: string;
+}
+/**
+ * Discovered component with annotations and metadata
+ */
+export interface DiscoveredComponent {
+    id: string;
+    title: string;
+    category: string;
+    risk?: RiskLevel;
+    testing?: TestingRequirements;
+    apis: CodexApiAnnotation[];
+    files: string[];
+    sourceDigest: string;
+}
+/**
+ * Parses @codex annotations from source code
+ * @param content - Source file content
+ * @returns Array of parsed CodexAnnotation objects
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"parseCodexAnnotations","stability":"stable","signature":"(content: string) => CodexAnnotation[]"}
+ */
+export declare function parseCodexAnnotations(content: string): CodexAnnotation[];
+/**
+ * Parses @codexApi annotations from source code
+ * @param content - Source file content
+ * @returns Array of parsed CodexApiAnnotation objects
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"parseCodexApiAnnotations","stability":"stable","signature":"(content: string) => CodexApiAnnotation[]"}
+ */
+export declare function parseCodexApiAnnotations(content: string): CodexApiAnnotation[];
+/**
+ * Normalizes source content for stable hashing by:
+ * - Removing comments (except annotations)
+ * - Normalizing whitespace
+ * - Preserving meaningful structure
+ * @param content - Source file content
+ * @returns Normalized content string
+ */
+export declare function normalizeSourceContent(content: string): string;
+/**
+ * Creates a stable content hash for a source file
+ * @param content - Source file content
+ * @returns SHA-256 hash of normalized content
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"createSourceDigest","stability":"stable","signature":"(content: string) => string"}
+ */
+export declare function createSourceDigest(content: string): string;
+/**
+ * Creates a canonical fingerprint for a discovered component
+ * @param component - DiscoveredComponent to fingerprint
+ * @returns SHA-256 hash of canonical representation
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"createCanonicalFingerprint","stability":"stable","signature":"(component: DiscoveredComponent) => string"}
+ */
+export declare function createCanonicalFingerprint(component: DiscoveredComponent): string;
+/**
+ * Discovers components from a single source file using annotations
+ * @param filePath - Path to the source file
+ * @param content - File content (optional, will read if not provided)
+ * @returns Array of discovered components
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"discoverComponentsFromFile","stability":"stable","signature":"(filePath: string, content?: string) => Promise<DiscoveredComponent[]>"}
+ */
+export declare function discoverComponentsFromFile(filePath: string, content?: string): Promise<DiscoveredComponent[]>;
+/**
+ * Validates annotation format and logs issues in DEV mode
+ * @param annotation - Annotation to validate
+ * @param type - Type of annotation for logging
+ * @returns True if valid
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"validateAnnotation","stability":"stable","signature":"(annotation: unknown, type: 'codex' | 'codexApi') => boolean"}
+ */
+export declare function validateAnnotation(annotation: unknown, type: 'codex' | 'codexApi'): boolean;

package/dist/annotations.js

@@ -0,0 +1,306 @@
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.annotations",
+ *   "title": "Codex Annotations",
+ *   "category": "feature"
+ * }
+ *
+ * Parses @codex and @codexApi annotations from source files to discover
+ * components and APIs. Provides content normalization and fingerprinting
+ * for change detection.
+ */
+import fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+/**
+ * Regex patterns for extracting annotations from source files.
+ *
+ * CODEX_JSON_BODY supports up to 3 levels of nesting (enough for
+ * `{ "testing": { "unit": { "required": true } } }`).
+ *
+ * Each BRACE_CONTENT level matches: non-brace/non-quote chars, quoted
+ * strings, or a deeper nested `{ ... }` group.
+ */
+const BRACE_CONTENT_L2 = String.raw `[^{}"]|"(?:[^"\\]|\\.)*"`;
+const BRACE_CONTENT_L1 = String.raw `${BRACE_CONTENT_L2}|\{(?:${BRACE_CONTENT_L2})*\}`;
+const BRACE_CONTENT_L0 = String.raw `${BRACE_CONTENT_L2}|\{(?:${BRACE_CONTENT_L1})*\}`;
+const CODEX_JSON_BODY = `(\\{(?:${BRACE_CONTENT_L0})*\\})`;
+const CODEX_ANNOTATION_REGEX = new RegExp(String.raw `/\*\*[\s*]*@codex[\s*]*` +
+    CODEX_JSON_BODY +
+    String.raw `[\s\S]*?\*/`, 'g');
+// Matches @codexApi on a starred JSDoc line (e.g. ` * @codexApi {...}`).
+// Used as a second pass inside JSDoc blocks found by JSDOC_BLOCK_REGEX
+// to prevent false positives from regular /* ... */ block comments.
+const CODEX_API_ANNOTATION_REGEX = new RegExp(String.raw `\*\s*@codexApi\s*` + CODEX_JSON_BODY, 'g');
+const JSDOC_BLOCK_REGEX = /\/\*\*[\s\S]*?\*\//g;
+/**
+ * Parses @codex annotations from source code
+ * @param content - Source file content
+ * @returns Array of parsed CodexAnnotation objects
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"parseCodexAnnotations","stability":"stable","signature":"(content: string) => CodexAnnotation[]"}
+ */
+export function parseCodexAnnotations(content) {
+    const annotations = [];
+    let match;
+    while ((match = CODEX_ANNOTATION_REGEX.exec(content)) !== null) {
+        try {
+            // Strip JSDoc line-prefix stars from multi-line JSON bodies
+            const jsonStr = match[1].replace(/^\s*\*\s?/gm, '');
+            const parsed = JSON.parse(jsonStr);
+            // Validate required fields and optional field shapes
+            if (validateAnnotation(parsed, 'codex')) {
+                annotations.push(parsed);
+                if (process.env.NODE_ENV === 'development') {
+                    console.log(`[Codex] Found @codex annotation: ${parsed.id}`);
+                }
+            }
+        }
+        catch (error) {
+            if (process.env.NODE_ENV === 'development') {
+                console.warn(`[Codex] Failed to parse @codex annotation:`, match[1], error);
+            }
+        }
+    }
+    return annotations;
+}
+/**
+ * Parses @codexApi annotations from source code
+ * @param content - Source file content
+ * @returns Array of parsed CodexApiAnnotation objects
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"parseCodexApiAnnotations","stability":"stable","signature":"(content: string) => CodexApiAnnotation[]"}
+ */
+export function parseCodexApiAnnotations(content) {
+    const annotations = [];
+    // Two-pass: first find JSDoc blocks (/** ... */), then extract
+    // @codexApi within each. This prevents false positives from
+    // regular /* ... */ block comments that happen to contain @codexApi.
+    JSDOC_BLOCK_REGEX.lastIndex = 0;
+    let blockMatch;
+    while ((blockMatch = JSDOC_BLOCK_REGEX.exec(content)) !== null) {
+        const block = blockMatch[0];
+        CODEX_API_ANNOTATION_REGEX.lastIndex = 0;
+        let match;
+        while ((match = CODEX_API_ANNOTATION_REGEX.exec(block)) !== null) {
+            try {
+                const jsonStr = match[1];
+                const parsed = JSON.parse(jsonStr);
+                // Validate required fields
+                if (parsed.parent && parsed.name) {
+                    annotations.push({
+                        ...parsed,
+                        stability: parsed.stability || 'stable',
+                    });
+                    if (process.env.NODE_ENV === 'development') {
+                        console.log(`[Codex] Found @codexApi annotation: ${parsed.parent}.${parsed.name}`);
+                    }
+                }
+                else {
+                    if (process.env.NODE_ENV === 'development') {
+                        console.warn(`[Codex] Invalid @codexApi annotation missing required fields:`, parsed);
+                    }
+                }
+            }
+            catch (error) {
+                if (process.env.NODE_ENV === 'development') {
+                    console.warn(`[Codex] Failed to parse @codexApi annotation:`, match[1], error);
+                }
+            }
+        }
+    }
+    return annotations;
+}
+/**
+ * Normalizes source content for stable hashing by:
+ * - Removing comments (except annotations)
+ * - Normalizing whitespace
+ * - Preserving meaningful structure
+ * @param content - Source file content
+ * @returns Normalized content string
+ */
+export function normalizeSourceContent(content) {
+    return (content
+        // Normalize line endings first for cross-platform consistency
+        .replace(/\r\n/g, '\n')
+        // Preserve JSDoc blocks (/** ... */) containing @codex or @codexApi annotations,
+        // remove all other block comments. Only JSDoc blocks are preserved because
+        // parseCodexApiAnnotations only extracts from /** ... */ blocks.
+        .replace(/\/\*[\s\S]*?\*\//g, match => /^\/\*\*/.test(match) && /@codex(?:Api)?/.test(match)
+        ? `ANNOTATION:${createHash('md5').update(match).digest('hex')}`
+        : '')
+        .replace(/\/\/.*$/gm, '')
+        // Normalize whitespace
+        .replace(/\s+/g, ' ')
+        .trim());
+}
+/**
+ * Creates a stable content hash for a source file
+ * @param content - Source file content
+ * @returns SHA-256 hash of normalized content
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"createSourceDigest","stability":"stable","signature":"(content: string) => string"}
+ */
+export function createSourceDigest(content) {
+    const normalized = normalizeSourceContent(content);
+    return createHash('sha256').update(normalized, 'utf8').digest('hex');
+}
+/**
+ * Creates a canonical fingerprint for a discovered component
+ * @param component - DiscoveredComponent to fingerprint
+ * @returns SHA-256 hash of canonical representation
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"createCanonicalFingerprint","stability":"stable","signature":"(component: DiscoveredComponent) => string"}
+ */
+export function createCanonicalFingerprint(component) {
+    const canonical = JSON.stringify({
+        id: component.id,
+        title: component.title,
+        category: component.category,
+        apis: component.apis.sort((a, b) => a.name.localeCompare(b.name)), // deterministic order
+        sourceDigest: component.sourceDigest,
+    });
+    return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+/**
+ * Discovers components from a single source file using annotations
+ * @param filePath - Path to the source file
+ * @param content - File content (optional, will read if not provided)
+ * @returns Array of discovered components
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"discoverComponentsFromFile","stability":"stable","signature":"(filePath: string, content?: string) => Promise<DiscoveredComponent[]>"}
+ */
+export async function discoverComponentsFromFile(filePath, content) {
+    const fileContent = content || (await fs.readFile(filePath, 'utf8').catch(() => ''));
+    if (!fileContent)
+        return [];
+    const codexAnnotations = parseCodexAnnotations(fileContent);
+    const apiAnnotations = parseCodexApiAnnotations(fileContent);
+    const sourceDigest = createSourceDigest(fileContent);
+    const components = [];
+    for (const annotation of codexAnnotations) {
+        // Find APIs that belong to this component
+        const componentApis = apiAnnotations.filter(api => api.parent === annotation.id);
+        components.push({
+            id: annotation.id,
+            title: annotation.title,
+            category: annotation.category,
+            risk: annotation.risk,
+            testing: annotation.testing,
+            apis: componentApis,
+            files: [filePath],
+            sourceDigest,
+        });
+        if (process.env.NODE_ENV === 'development') {
+            console.log(`[Codex] Discovered component: ${annotation.id} with ${componentApis.length} APIs`);
+        }
+    }
+    return components;
+}
+/**
+ * Validates annotation format and logs issues in DEV mode
+ * @param annotation - Annotation to validate
+ * @param type - Type of annotation for logging
+ * @returns True if valid
+ *
+ * @codexApi {"parent":"pithy.codex.annotations","name":"validateAnnotation","stability":"stable","signature":"(annotation: unknown, type: 'codex' | 'codexApi') => boolean"}
+ */
+export function validateAnnotation(annotation, type) {
+    if (typeof annotation !== 'object' || annotation === null) {
+        return false;
+    }
+    const obj = annotation;
+    if (type === 'codex') {
+        const required = ['id', 'title', 'category'];
+        const missing = required.filter(field => !obj[field]);
+        if (missing.length > 0) {
+            if (process.env.NODE_ENV === 'development') {
+                console.warn(`[Codex] Invalid @codex annotation missing: ${missing.join(', ')}`, obj);
+            }
+            return false;
+        }
+        const validCategories = [
+            'feature',
+            'directive',
+            'runtime',
+            'compiler',
+            'plugin',
+            'types',
+        ];
+        if (!validCategories.includes(obj.category)) {
+            if (process.env.NODE_ENV === 'development') {
+                console.warn(`[Codex] Invalid @codex category: ${obj.category}. Must be one of: ${validCategories.join(', ')}`);
+            }
+            return false;
+        }
+        // Validate optional risk field
+        if (obj.risk !== undefined) {
+            const validRiskLevels = ['critical', 'high', 'medium', 'low'];
+            if (!validRiskLevels.includes(obj.risk)) {
+                if (process.env.NODE_ENV === 'development') {
+                    console.warn(`[Codex] Invalid @codex risk level: ${obj.risk}. Must be one of: ${validRiskLevels.join(', ')}`);
+                }
+                return false;
+            }
+        }
+        // Validate optional testing field structure
+        if (obj.testing !== undefined) {
+            if (typeof obj.testing !== 'object' || obj.testing === null) {
+                if (process.env.NODE_ENV === 'development') {
+                    console.warn(`[Codex] Invalid @codex testing field: must be an object`);
+                }
+                return false;
+            }
+            const testing = obj.testing;
+            const validTestLevels = ['unit', 'integration', 'e2e'];
+            for (const key of Object.keys(testing)) {
+                if (!validTestLevels.includes(key)) {
+                    if (process.env.NODE_ENV === 'development') {
+                        console.warn(`[Codex] Invalid @codex testing level: ${key}. Must be one of: ${validTestLevels.join(', ')}`);
+                    }
+                    return false;
+                }
+                const rawLevel = testing[key];
+                if (typeof rawLevel !== 'object' || rawLevel === null) {
+                    if (process.env.NODE_ENV === 'development') {
+                        console.warn(`[Codex] Invalid @codex testing.${key}: must be an object`);
+                    }
+                    return false;
+                }
+                const level = rawLevel;
+                if ('required' in level && typeof level.required !== 'boolean') {
+                    if (process.env.NODE_ENV === 'development') {
+                        console.warn(`[Codex] Invalid @codex testing.${key}.required: must be a boolean`);
+                    }
+                    return false;
+                }
+                if ('coverage' in level &&
+                    (typeof level.coverage !== 'number' ||
+                        level.coverage < 0 ||
+                        level.coverage > 100)) {
+                    if (process.env.NODE_ENV === 'development') {
+                        console.warn(`[Codex] Invalid @codex testing.${key}.coverage: must be a number between 0 and 100`);
+                    }
+                    return false;
+                }
+                if ('covered' in level && typeof level.covered !== 'boolean') {
+                    if (process.env.NODE_ENV === 'development') {
+                        console.warn(`[Codex] Invalid @codex testing.${key}.covered: must be a boolean`);
+                    }
+                    return false;
+                }
+            }
+        }
+    }
+    if (type === 'codexApi') {
+        const required = ['parent', 'name'];
+        const missing = required.filter(field => !obj[field]);
+        if (missing.length > 0) {
+            if (process.env.NODE_ENV === 'development') {
+                console.warn(`[Codex] Invalid @codexApi annotation missing: ${missing.join(', ')}`, obj);
+            }
+            return false;
+        }
+    }
+    return true;
+}

package/dist/apply.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/apply.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.apply",
+ *   "title": "Entry Applier",
+ *   "category": "feature"
+ * }
+ *
+ * Applies reviewed codex entries to the knowledge base. Reads review.md for
+ * [x]-marked approvals, validates each proposal against the Zod schema, and
+ * copies approved JSON entries from .proposals/ into the codex/ directory.
+ */
+import fs from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { codexSchema } from './schema.js';
+import { execa } from 'execa';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+async function main() {
+    const root = process.argv.includes('--root')
+        ? process.argv[process.argv.indexOf('--root') + 1]
+        : join(__dirname, '../../..');
+    const proposalsDir = join(root, 'codex', '.proposals');
+    const reviewPath = join(proposalsDir, 'review.md');
+    const review = await fs.readFile(reviewPath, 'utf8').catch(() => '');
+    const APPROVED_RE = /^\s*-\s*\[(x|X)\]\s*.*?\*\*([^*]+)\*\*/gmu;
+    const matches = Array.from(review.matchAll(APPROVED_RE));
+    console.log(`[DEBUG] Found ${matches.length} regex matches`);
+    if (matches.length > 0) {
+        console.log(`[DEBUG] First match: '${matches[0][2].trim()}'`);
+    }
+    const approvedIds = matches.map(m => m[2].trim());
+    if (approvedIds.length === 0) {
+        console.log('No approved proposals found. Edit codex/.proposals/review.md and mark with [x].');
+        return;
+    }
+    const outDir = join(root, 'codex');
+    await fs.mkdir(outDir, { recursive: true });
+    for (const id of approvedIds) {
+        const file = join(proposalsDir, `${id}.json`);
+        const raw = await fs.readFile(file, 'utf8');
+        const json = JSON.parse(raw);
+        json.updated = new Date().toISOString();
+        // Preserve hash metadata for future change detection
+        if (json.meta?.hash) {
+            if (process.env.NODE_ENV === 'development') {
+                console.log(`[Codex] Preserving hash for ${id}: ${json.meta.hash.substring(0, 8)}...`);
+            }
+        }
+        const parsed = codexSchema.safeParse(json);
+        if (!parsed.success) {
+            console.error(`❌ Invalid entry ${id}:`, parsed.error.issues.map(i => i.message).join('; '));
+            continue;
+        }
+        const dest = join(outDir, `${id}.json`);
+        try {
+            await fs.access(dest);
+            console.log(`↷ Updating ${basename(dest)}`);
+        }
+        catch {
+            console.log(`+ Creating ${basename(dest)}`);
+        }
+        await fs.writeFile(dest, JSON.stringify(parsed.data, null, 2));
+        console.log(`✅ Wrote ${basename(dest)}`);
+    }
+    // Rebuild index via the package script
+    try {
+        await execa('pnpm', ['-w', '--filter', '@pithyjs/codex', 'index'], {
+            stdio: 'inherit',
+        });
+    }
+    catch {
+        console.log('Run `pnpm -w --filter @pithyjs/codex index` manually if needed.');
+    }
+}
+main().catch(e => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/changed-scope.d.ts

@@ -0,0 +1,23 @@
+/** @codex { "id": "pithy.codex.changed-scope", "title": "Codex Changed-File Scope", "category": "types" } */
+/**
+ * Which files `--changed-only` looks at.
+ *
+ * These are GIT PATHSPECS, not globs, and the difference is not cosmetic: git's
+ * `*` already crosses `/`, while its doubled form requires at least one
+ * intervening directory. The previous spelling resolved 875 files and dropped
+ * every file sitting directly in a `src/` — 114 of them, including
+ * `packages/signals/src/signal.ts` and `apps/studio/src/main.ts` — while the
+ * same string handed to globby in `scan.ts` matches all 989. One spelling, two
+ * engines, two scopes.
+ *
+ * The test directories are here because `codex-sync.yml` triggers on them: a
+ * marker-only change would otherwise reach an empty changed set and return at
+ * "Nothing to sync". The marker itself is harvested by the pipeline step, which
+ * globs `testPatterns` and is not changed-scoped — this keeps the two filters
+ * describing one set rather than gating that.
+ *
+ * Its own module because `sync.ts` calls `main()` at import: anything importing
+ * the constant from there would start a full sync during module evaluation.
+ */
+/** @codexApi {"parent":"pithy.codex.changed-scope","name":"CHANGED_ONLY_PATHSPEC","stability":"stable","signature":"readonly string[]"} */
+export declare const CHANGED_ONLY_PATHSPEC: readonly string[];

package/dist/changed-scope.js

@@ -0,0 +1,31 @@
+/** @codex { "id": "pithy.codex.changed-scope", "title": "Codex Changed-File Scope", "category": "types" } */
+/**
+ * Which files `--changed-only` looks at.
+ *
+ * These are GIT PATHSPECS, not globs, and the difference is not cosmetic: git's
+ * `*` already crosses `/`, while its doubled form requires at least one
+ * intervening directory. The previous spelling resolved 875 files and dropped
+ * every file sitting directly in a `src/` — 114 of them, including
+ * `packages/signals/src/signal.ts` and `apps/studio/src/main.ts` — while the
+ * same string handed to globby in `scan.ts` matches all 989. One spelling, two
+ * engines, two scopes.
+ *
+ * The test directories are here because `codex-sync.yml` triggers on them: a
+ * marker-only change would otherwise reach an empty changed set and return at
+ * "Nothing to sync". The marker itself is harvested by the pipeline step, which
+ * globs `testPatterns` and is not changed-scoped — this keeps the two filters
+ * describing one set rather than gating that.
+ *
+ * Its own module because `sync.ts` calls `main()` at import: anything importing
+ * the constant from there would start a full sync during module evaluation.
+ */
+/** @codexApi {"parent":"pithy.codex.changed-scope","name":"CHANGED_ONLY_PATHSPEC","stability":"stable","signature":"readonly string[]"} */
+export const CHANGED_ONLY_PATHSPEC = [
+    'packages/*/src/*.ts',
+    'packages/*/src/*.js',
+    'apps/*/src/*.ts',
+    'apps/*/src/*.js',
+    'packages/*/tests/*.ts',
+    'apps/*/tests/*.ts',
+    'e2e/tests/*.ts',
+];

package/dist/check.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/check.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * @codex
+ * {
+ *   "id": "pithy.codex.check",
+ *   "title": "Integrity Checker",
+ *   "category": "feature"
+ * }
+ *
+ * Validates codex entries against source annotations. Walks all JSON files in
+ * codex/, validates each against the Zod schema, checks for duplicate IDs,
+ * verifies ISO date formats, and reports errors/warnings.
+ */
+import fs from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { codexSchema } from './schema.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '../../..');
+const codexDir = join(repoRoot, 'codex');
+async function getJsonFiles(dir) {
+    const out = [];
+    try {
+        const dirents = await fs.readdir(dir, { withFileTypes: true });
+        for (const d of dirents) {
+            const p = join(dir, d.name);
+            // Skip .proposals directory to avoid duplicate ID errors
+            if (d.isDirectory() && d.name !== '.proposals') {
+                out.push(...(await getJsonFiles(p)));
+            }
+            else if (d.isFile() && p.endsWith('.json')) {
+                out.push(p);
+            }
+        }
+    }
+    catch {
+        // no codex dir yet
+    }
+    return out;
+}
+function isIsoDate(s) {
+    // Zod .datetime() already checks, but we double-check for clarity
+    const d = new Date(s);
+    return !Number.isNaN(d.valueOf()) && /^\d{4}-\d{2}-\d{2}T/.test(s);
+}
+async function main() {
+    const files = await getJsonFiles(codexDir);
+    const issues = [];
+    const entriesById = new Map();
+    for (const file of files) {
+        try {
+            const raw = await fs.readFile(file, 'utf8');
+            const json = JSON.parse(raw);
+            const parsed = codexSchema.safeParse(json);
+            if (!parsed.success) {
+                issues.push({
+                    type: 'error',
+                    file,
+                    msg: 'Schema validation failed: ' +
+                        parsed.error.issues.map(i => i.message).join('; '),
+                });
+                continue;
+            }
+            const e = parsed.data;
+            // Duplicate ID check
+            if (entriesById.has(e.id)) {
+                const prev = entriesById.get(e.id);
+                issues.push({
+                    type: 'error',
+                    file,
+                    msg: `Duplicate id "${e.id}" also used in ${prev.file}`,
+                });
+            }
+            else {
+                entriesById.set(e.id, { file, entry: e });
+            }
+            // ISO date sanity (redundant but explicit)
+            if (!isIsoDate(e.updated)) {
+                issues.push({
+                    type: 'error',
+                    file,
+                    msg: `updated is not a valid ISO date: "${e.updated}"`,
+                });
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            issues.push({ type: 'error', file, msg: `Read/parse failed: ${msg}` });
+        }
+    }
+    // Related reference checks (warn if dangling)
+    for (const { file, entry } of entriesById.values()) {
+        for (const rel of entry.related ?? []) {
+            if (!entriesById.has(rel)) {
+                issues.push({
+                    type: 'warn',
+                    file,
+                    msg: `related references missing id "${rel}"`,
+                });
+            }
+        }
+    }
+    // Output
+    const errors = issues.filter(i => i.type === 'error');
+    const warns = issues.filter(i => i.type === 'warn');
+    for (const i of issues) {
+        const tag = i.type === 'error' ? '❌' : '⚠️';
+        console.log(`${tag} ${i.type.toUpperCase()} in ${i.file}: ${i.msg}`);
+    }
+    console.log(`\nCodex check complete: ${entriesById.size} entries, ${errors.length} error(s), ${warns.length} warning(s).`);
+    if (errors.length > 0)
+        process.exit(1);
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};