reffy-cli 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roberto L. Delgado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# reffy
+
+Reffy is intended as an ideation layer for spec-driven development (SDD) in straightforward, version controlled and agent-friendly markdown files.
+
+## Install
+
+Recommended usage in any repo:
+
+```bash
+npm install -g reffy-cli
+```
+
+The install runs this package's `prepare` step, which builds `dist/` automatically.
+
+## Quickstart (CLI-only)
+
+Inside your project:
+
+```bash
+reffy init
+reffy bootstrap
+reffy doctor
+reffy reindex
+reffy validate
+reffy summarize
+```
+
+Command summary:
+
+- `reffy init`: idempotently creates/updates root `AGENTS.md` managed block and `.references/AGENTS.md`.
+- `reffy bootstrap`: idempotently runs `init`, ensures `.references/` structure exists, then reindexes artifacts.
+- `reffy doctor`: diagnoses required Reffy setup and optional tool availability.
+- `reffy reindex`: reconciles `.references/manifest.json` with `.references/artifacts` by adding missing files and removing stale entries.
+- `reffy validate`: validates `.references/manifest.json` against manifest v1 contract.
+- `reffy summarize`: generates a read-only handoff summary from indexed artifacts.
+
+Output modes:
+
+- `--output text` (default)
+- `--output json`
+- `--json` (shortcut for `--output json`)
+
+Examples:
+
+```bash
+reffy reindex --output json
+reffy validate --repo .
+reffy doctor --output text
+reffy doctor --output json
+reffy summarize --output text
+reffy summarize --output json
+```
+
+## Using Reffy With SDD Frameworks (OpenSpec Example)
+
+`reffy` is designed to complement spec-driven development workflows rather than replace them. A common pattern is:
+
+1. Use Reffy for ideation and context capture in `.references/`.
+2. Use an SDD framework (for example [OpenSpec](https://github.com/Fission-AI/OpenSpec)) for formal proposals/specs/tasks.
+3. Keep a clear handoff from exploratory artifacts to formal specs.
+
+Reference implementation in this repo:
+
+- `AGENTS.md`: contains both managed instruction blocks and encodes sequencing.
+- `AGENTS.md`: Reffy block routes ideation/exploration requests to `@/.references/AGENTS.md`.
+- `AGENTS.md`: OpenSpec block routes planning/proposal/spec requests to `@/openspec/AGENTS.md`.
+- `.references/AGENTS.md`: defines Reffy as the ideation/context layer and documents handoff expectations to OpenSpec.
+- `openspec/AGENTS.md`: defines OpenSpec as the formal planning/specification workflow after ideation is stable.
+- `src/cli.ts`: `reffy init`/`reffy bootstrap` enforce this integration by idempotently writing the managed Reffy guidance into `AGENTS.md` and `.references/AGENTS.md`.
+
+Practical connection pattern for any repo:
+
+1. Run `reffy init` to install/refresh the Reffy instruction layer.
+2. Keep your SDD framework instructions (for example OpenSpec) in the same root `AGENTS.md`.
+3. During planning, cite only relevant Reffy artifacts from `.references/artifacts/` in your proposal/spec docs.
+4. Continue implementation in your SDD framework's normal review/approval process.
+
+## Develop
+
+For local development of this repo:
+
+```bash
+npm install
+npm run build
+npm run check
+npm test
+```

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { runDoctor } from "./doctor.js";
+import { ReferencesStore } from "./storage.js";
+import { summarizeArtifacts } from "./summarize.js";
+const REFFY_ASCII = [
+    "            __  __      ",
+    " _ __ ___  / _|/ _|_   _",
+    "| '__/ _ \\| |_| |_| | | |",
+    "| | |  __/|  _|  _| |_| |",
+    "|_|  \\___||_| |_|  \\__, |",
+    "                   |___/ ",
+].join("\n");
+const REFFY_BLOCK = `<!-- REFFY:START -->
+# Reffy Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open \`@/.references/AGENTS.md\` when the request:
+- Mentions early-stage ideation, exploration, brainstorming, or raw notes
+- Needs context before drafting specs or proposals
+- Refers to "reffy", "references", "explore", or "context layer"
+
+Use \`@/.references/AGENTS.md\` to learn:
+- Reffy workflow and artifact conventions
+- How Reffy and OpenSpec should be sequenced
+- How to store and consume ideation context in \`.references/\`
+
+Keep this managed block so \`reffy init\` can refresh the instructions.
+
+<!-- REFFY:END -->`;
+const REFFY_AGENTS_RELATIVE = path.join(".references", "AGENTS.md");
+const REFFY_AGENTS_CONTENT = `# Reffy Instructions
+
+These instructions are for AI assistants working in this project.
+
+## TL;DR Checklist
+
+- Decide whether Reffy ideation is needed for this request.
+- If needed, read existing context in \`.references/artifacts/\`.
+- Add/update exploratory artifacts and keep them concise.
+- Run \`reffy reindex\` and \`reffy validate\` after artifact changes.
+- After ideation approval, run \`reffy summarize --output json\` and pick only directly relevant artifacts for proposal citations.
+
+## When To Use Reffy
+
+Use Reffy first when the request:
+- Mentions early-stage ideation, exploration, brainstorming, or raw notes
+- Needs context gathering before drafting a concrete implementation plan
+- Refers to "reffy", "references", "explore", "context layer", or research artifacts
+
+## When To Skip Reffy
+
+You can skip Reffy when the request is:
+- A narrow bug fix that does not need exploratory context
+- A small refactor with no requirement/design ambiguity
+- A formatting, typing, or tooling-only update with clear scope
+
+## Reffy Workflow
+
+1. Read existing artifacts in \`.references/artifacts/\`.
+2. Add or update artifacts to capture exploratory context.
+3. Run \`reffy reindex\` to index newly added files into \`.references/manifest.json\`.
+4. Run \`reffy validate\` to verify manifest contract compliance.
+
+## Relationship To OpenSpec
+
+- Reffy is the ideation/context layer.
+- OpenSpec is the formal planning/spec layer.
+- After ideation stabilizes, hand off to OpenSpec by following \`@/openspec/AGENTS.md\`.
+- Do not duplicate full proposal/spec content in Reffy artifacts; summarize and link to OpenSpec outputs.
+
+## OpenSpec Citation Rules
+
+When an OpenSpec proposal is informed by Reffy artifacts:
+- After ideation approval, run \`reffy summarize --output json\` to shortlist candidate artifacts.
+- Include a short "Reffy References" subsection in \`proposal.md\` (or design notes if more appropriate).
+- Cite only artifact filenames that directly informed the proposal's problem, scope, decisions, or constraints.
+- Cite artifact filenames and intent, for example:
+  - \`testing.md\` - early constraints and tradeoffs for manifest validation
+- Do not include generic process artifacts or unrelated notes just because they exist.
+- Keep citations at proposal/design level; task-by-task traceability is optional unless the change is high risk.
+- If no Reffy artifacts informed the change, explicitly state "No Reffy references used."
+
+### Reusable Proposal Snippet
+
+Use this in \`openspec/changes/<change-id>/proposal.md\`:
+
+\`\`\`md
+## Reffy References
+- \`artifact-name.md\` - short note about how it informed this proposal
+\`\`\`
+
+If none were used:
+
+\`\`\`md
+## Reffy References
+No Reffy references used.
+\`\`\`
+
+## Artifact Conventions
+
+- Treat \`.references/\` as a repository-local guidance and ideation context layer.
+- Keep artifact names clear and stable.
+- Prefer markdown notes for exploratory content.
+- Keep manifests machine-readable and schema-compliant (version 1).
+`;
+const REFFY_START = "<!-- REFFY:START -->";
+const REFFY_END = "<!-- REFFY:END -->";
+const OPENSPEC_START = "<!-- OPENSPEC:START -->";
+function upsertReffyBlock(content) {
+    if (content.includes(REFFY_START) && content.includes(REFFY_END)) {
+        const prefix = content.split(REFFY_START)[0] ?? "";
+        const suffix = content.split(REFFY_END, 2)[1] ?? "";
+        const trimmedSuffix = suffix.trimStart();
+        return trimmedSuffix.length > 0 ? `${prefix}${REFFY_BLOCK}\n\n${trimmedSuffix}` : `${prefix}${REFFY_BLOCK}\n`;
+    }
+    if (content.includes(OPENSPEC_START)) {
+        const [before, after] = content.split(OPENSPEC_START, 2);
+        return `${before.trimEnd()}\n\n${REFFY_BLOCK}\n\n${OPENSPEC_START}${after}`;
+    }
+    return content.trim().length > 0 ? `${REFFY_BLOCK}\n\n${content.trimStart()}` : `${REFFY_BLOCK}\n`;
+}
+async function initAgents(repoRoot) {
+    const agentsPath = path.join(repoRoot, "AGENTS.md");
+    const reffyAgentsPath = path.join(repoRoot, REFFY_AGENTS_RELATIVE);
+    let content = "";
+    try {
+        content = await fs.readFile(agentsPath, "utf8");
+    }
+    catch {
+        content = "";
+    }
+    const updated = upsertReffyBlock(content);
+    await fs.mkdir(path.dirname(reffyAgentsPath), { recursive: true });
+    await fs.writeFile(agentsPath, updated, "utf8");
+    await fs.writeFile(reffyAgentsPath, REFFY_AGENTS_CONTENT, "utf8");
+    return { root_agents_path: agentsPath, reffy_agents_path: reffyAgentsPath };
+}
+function parseRepoArg(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--repo requires a path");
+            return path.resolve(value);
+        }
+        if (arg.startsWith("--repo=")) {
+            const value = arg.split("=", 2)[1];
+            if (!value)
+                throw new Error("--repo requires a path");
+            return path.resolve(value);
+        }
+    }
+    return process.cwd();
+}
+function parseOutputMode(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--json")
+            return "json";
+        if (arg === "--output") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--output requires a value: text|json");
+            if (value !== "text" && value !== "json")
+                throw new Error(`Unsupported output mode: ${value}`);
+            return value;
+        }
+        if (arg.startsWith("--output=")) {
+            const value = arg.split("=", 2)[1];
+            if (value !== "text" && value !== "json")
+                throw new Error(`Unsupported output mode: ${value}`);
+            return value;
+        }
+    }
+    return "text";
+}
+function printResult(mode, payload) {
+    if (mode === "json") {
+        console.log(JSON.stringify(payload, null, 2));
+    }
+}
+function printBanner(mode) {
+    if (mode === "text") {
+        console.log(REFFY_ASCII);
+        console.log("");
+    }
+}
+function usage() {
+    return [
+        "Usage: reffy <command> [--repo PATH] [--output text|json]",
+        "",
+        "Commands:",
+        "  init       Ensure root AGENTS.md block and .references/AGENTS.md are up to date.",
+        "  bootstrap  Run init, ensure .references structure exists, then reindex artifacts.",
+        "  doctor     Diagnose required Reffy setup and optional tool availability.",
+        "  reindex    Scan .references/artifacts and add missing files to manifest.",
+        "  validate   Validate .references/manifest.json against manifest v1 contract.",
+        "  summarize  Generate a read-only summary of indexed Reffy artifacts.",
+    ].join("\n");
+}
+function printSection(title, values) {
+    console.log(`${title}:`);
+    if (values.length === 0) {
+        console.log("- (none)");
+        return;
+    }
+    for (const value of values) {
+        console.log(`- ${value}`);
+    }
+}
+async function main() {
+    const [, , command, ...rest] = process.argv;
+    const output = parseOutputMode(rest);
+    printBanner(output);
+    if (!command) {
+        console.error(usage());
+        return 1;
+    }
+    if (command === "init") {
+        const repoRoot = parseRepoArg(rest);
+        const agents = await initAgents(repoRoot);
+        const payload = { status: "ok", command: "init", ...agents };
+        if (output === "json") {
+            printResult(output, payload);
+        }
+        else {
+            console.log(`Updated ${agents.root_agents_path}`);
+            console.log(`Updated ${agents.reffy_agents_path}`);
+        }
+        return 0;
+    }
+    if (command === "bootstrap") {
+        const repoRoot = parseRepoArg(rest);
+        const agents = await initAgents(repoRoot);
+        const store = new ReferencesStore(repoRoot);
+        const reindex = await store.reindexArtifacts();
+        const payload = {
+            status: "ok",
+            command: "bootstrap",
+            ...agents,
+            refs_dir: store.refsDir,
+            manifest_path: store.manifestPath,
+            reindex,
+        };
+        if (output === "json") {
+            printResult(output, payload);
+        }
+        else {
+            console.log(`Bootstrapped ${store.refsDir}`);
+            console.log(`Updated ${agents.root_agents_path}`);
+            console.log(`Updated ${agents.reffy_agents_path}`);
+            console.log(`Reindex: added=${String(reindex.added)} removed=${String(reindex.removed)} total=${String(reindex.total)}`);
+        }
+        return 0;
+    }
+    if (command === "reindex") {
+        const repoRoot = parseRepoArg(rest);
+        const store = new ReferencesStore(repoRoot);
+        const reindex = await store.reindexArtifacts();
+        const payload = { status: "ok", command: "reindex", ...reindex };
+        if (output === "json") {
+            printResult(output, payload);
+        }
+        else {
+            console.log(`Reindex complete: added=${String(reindex.added)} removed=${String(reindex.removed)} total=${String(reindex.total)}`);
+        }
+        return 0;
+    }
+    if (command === "doctor") {
+        const repoRoot = parseRepoArg(rest);
+        const report = await runDoctor(repoRoot);
+        const status = report.summary.required_failed > 0 ? "error" : "ok";
+        const payload = { status, command: "doctor", ...report };
+        if (output === "json") {
+            printResult(output, payload);
+        }
+        else {
+            const required = report.checks.filter((check) => check.level === "required");
+            const optional = report.checks.filter((check) => check.level === "optional");
+            console.log("Required Checks:");
+            for (const check of required) {
+                console.log(`- ${check.ok ? "PASS" : "FAIL"} ${check.id}: ${check.message}`);
+            }
+            console.log("");
+            console.log("Optional Checks:");
+            for (const check of optional) {
+                console.log(`- ${check.ok ? "PASS" : "WARN"} ${check.id}: ${check.message}`);
+            }
+            console.log("");
+            console.log(`Summary: required_failed=${String(report.summary.required_failed)} optional_failed=${String(report.summary.optional_failed)}`);
+        }
+        return status === "ok" ? 0 : 1;
+    }
+    if (command === "validate") {
+        const repoRoot = parseRepoArg(rest);
+        const store = new ReferencesStore(repoRoot);
+        const result = await store.validateManifest();
+        const payload = { status: result.ok ? "ok" : "error", command: "validate", ...result };
+        if (output === "json") {
+            printResult(output, payload);
+        }
+        else if (result.ok) {
+            console.log(`Manifest valid: artifacts=${String(result.artifact_count)}`);
+            if (result.warnings.length > 0) {
+                for (const warning of result.warnings) {
+                    console.log(`warn: ${warning}`);
+                }
+            }
+        }
+        else {
+            console.error(`Manifest invalid: ${String(result.errors.length)} error(s)`);
+            for (const error of result.errors) {
+                console.error(`error: ${error}`);
+            }
+            for (const warning of result.warnings) {
+                console.error(`warn: ${warning}`);
+            }
+        }
+        return result.ok ? 0 : 1;
+    }
+    if (command === "summarize") {
+        const repoRoot = parseRepoArg(rest);
+        const store = new ReferencesStore(repoRoot);
+        const validation = await store.validateManifest();
+        if (!validation.ok) {
+            const payload = { status: "error", command: "summarize", ...validation };
+            if (output === "json") {
+                printResult(output, payload);
+            }
+            else {
+                console.error(`Cannot summarize: manifest invalid (${String(validation.errors.length)} error(s))`);
+                for (const error of validation.errors) {
+                    console.error(`error: ${error}`);
+                }
+            }
+            return 1;
+        }
+        const summary = await summarizeArtifacts(store);
+        const payload = { status: "ok", command: "summarize", ...summary };
+        if (output === "json") {
+            printResult(output, payload);
+        }
+        else {
+            printSection("Themes", summary.themes);
+            console.log("");
+            printSection("Open Questions", summary.open_questions);
+            console.log("");
+            printSection("Candidate Changes", summary.candidate_changes);
+            console.log("");
+            console.log("Suggested Reffy References:");
+            if (summary.suggested_reffy_references.length === 0) {
+                console.log("- (none)");
+            }
+            else {
+                for (const reference of summary.suggested_reffy_references) {
+                    console.log(`- ${reference.filename} - ${reference.reason}`);
+                }
+            }
+        }
+        return 0;
+    }
+    console.error(`Unknown command: ${command}`);
+    console.error(usage());
+    return 1;
+}
+void main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(String(error));
+    process.exitCode = 1;
+});

package/dist/doctor.d.ts

@@ -0,0 +1,21 @@
+type CheckLevel = "required" | "optional";
+export interface DoctorCheck {
+    id: string;
+    level: CheckLevel;
+    ok: boolean;
+    message: string;
+}
+export interface DoctorReport {
+    checks: DoctorCheck[];
+    summary: {
+        required_total: number;
+        required_failed: number;
+        optional_total: number;
+        optional_failed: number;
+    };
+}
+export interface DoctorOptions {
+    checkOpenSpec?: () => boolean;
+}
+export declare function runDoctor(repoRoot: string, options?: DoctorOptions): Promise<DoctorReport>;
+export {};

package/dist/doctor.js

@@ -0,0 +1,92 @@
+import { spawnSync } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { validateManifest } from "./manifest.js";
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultOpenSpecCheck() {
+    const result = spawnSync("openspec", ["--version"], { stdio: "ignore" });
+    return result.error === undefined;
+}
+function summarizeChecks(checks) {
+    const required = checks.filter((check) => check.level === "required");
+    const optional = checks.filter((check) => check.level === "optional");
+    return {
+        required_total: required.length,
+        required_failed: required.filter((check) => !check.ok).length,
+        optional_total: optional.length,
+        optional_failed: optional.filter((check) => !check.ok).length,
+    };
+}
+export async function runDoctor(repoRoot, options) {
+    const checks = [];
+    const refsDir = path.join(repoRoot, ".references");
+    const artifactsDir = path.join(refsDir, "artifacts");
+    const manifestPath = path.join(refsDir, "manifest.json");
+    const rootAgentsPath = path.join(repoRoot, "AGENTS.md");
+    const refsAgentsPath = path.join(refsDir, "AGENTS.md");
+    const refsDirExists = await pathExists(refsDir);
+    checks.push({
+        id: "refs_dir_exists",
+        level: "required",
+        ok: refsDirExists,
+        message: refsDirExists ? ".references directory found" : ".references directory is missing",
+    });
+    const artifactsDirExists = await pathExists(artifactsDir);
+    checks.push({
+        id: "artifacts_dir_exists",
+        level: "required",
+        ok: artifactsDirExists,
+        message: artifactsDirExists ? ".references/artifacts directory found" : ".references/artifacts directory is missing",
+    });
+    const rootAgentsExists = await pathExists(rootAgentsPath);
+    checks.push({
+        id: "root_agents_exists",
+        level: "required",
+        ok: rootAgentsExists,
+        message: rootAgentsExists ? "AGENTS.md found" : "AGENTS.md is missing",
+    });
+    const refsAgentsExists = await pathExists(refsAgentsPath);
+    checks.push({
+        id: "refs_agents_exists",
+        level: "required",
+        ok: refsAgentsExists,
+        message: refsAgentsExists ? ".references/AGENTS.md found" : ".references/AGENTS.md is missing",
+    });
+    const manifestExists = await pathExists(manifestPath);
+    if (!manifestExists) {
+        checks.push({
+            id: "manifest_valid",
+            level: "required",
+            ok: false,
+            message: ".references/manifest.json is missing",
+        });
+    }
+    else {
+        const manifestResult = await validateManifest(manifestPath, artifactsDir);
+        checks.push({
+            id: "manifest_valid",
+            level: "required",
+            ok: manifestResult.ok,
+            message: manifestResult.ok
+                ? `.references/manifest.json is valid (artifacts=${String(manifestResult.artifact_count)})`
+                : `manifest invalid: ${manifestResult.errors.join("; ")}`,
+        });
+    }
+    const checkOpenSpec = options?.checkOpenSpec ?? defaultOpenSpecCheck;
+    const hasOpenSpec = checkOpenSpec();
+    checks.push({
+        id: "openspec_available",
+        level: "optional",
+        ok: hasOpenSpec,
+        message: hasOpenSpec ? "openspec command is available" : "openspec command not found on PATH",
+    });
+    return { checks, summary: summarizeChecks(checks) };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ReferencesStore } from "./storage.js";
+export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./manifest.js";
+export { runDoctor } from "./doctor.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ReferencesStore } from "./storage.js";
+export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./manifest.js";
+export { runDoctor } from "./doctor.js";

package/dist/manifest.d.ts

@@ -0,0 +1,15 @@
+import type { Manifest } from "./types.js";
+export declare const MANIFEST_VERSION = 1;
+export declare function allowedKindExtensions(): Record<string, string[]>;
+export declare function inferArtifactType(filePath: string): {
+    kind: string;
+    mime_type: string;
+};
+export interface ManifestValidationResult {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+    artifact_count: number;
+}
+export declare function validateManifest(manifestPath: string, artifactsDir: string): Promise<ManifestValidationResult>;
+export declare function isManifest(value: unknown): value is Manifest;

package/dist/manifest.js

@@ -0,0 +1,161 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { lookup as mimeLookup } from "mime-types";
+export const MANIFEST_VERSION = 1;
+const KIND_EXTENSIONS = {
+    note: [".md"],
+    json: [".json"],
+    diagram: [".excalidraw"],
+    image: [".png", ".jpg", ".jpeg"],
+    html: [".html", ".htm"],
+    pdf: [".pdf"],
+    doc: [".doc", ".docx"],
+    file: [],
+};
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isIsoDate(value) {
+    if (typeof value !== "string")
+        return false;
+    return !Number.isNaN(Date.parse(value));
+}
+function relativePathSafe(filename) {
+    if (path.isAbsolute(filename))
+        return false;
+    const normalized = path.normalize(filename);
+    return !normalized.startsWith("..") && !normalized.includes(`${path.sep}..${path.sep}`);
+}
+export function allowedKindExtensions() {
+    return Object.fromEntries(Object.entries(KIND_EXTENSIONS).map(([kind, extensions]) => [kind, [...extensions]]));
+}
+export function inferArtifactType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".excalidraw")
+        return { kind: "diagram", mime_type: "application/json" };
+    if (ext === ".png")
+        return { kind: "image", mime_type: "image/png" };
+    if (ext === ".jpg" || ext === ".jpeg")
+        return { kind: "image", mime_type: "image/jpeg" };
+    if (ext === ".html" || ext === ".htm")
+        return { kind: "html", mime_type: "text/html" };
+    if (ext === ".pdf")
+        return { kind: "pdf", mime_type: "application/pdf" };
+    if (ext === ".doc")
+        return { kind: "doc", mime_type: "application/msword" };
+    if (ext === ".docx") {
+        return {
+            kind: "doc",
+            mime_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        };
+    }
+    if (ext === ".json")
+        return { kind: "json", mime_type: "application/json" };
+    if (ext === ".md")
+        return { kind: "note", mime_type: "text/markdown" };
+    const guessed = mimeLookup(path.basename(filePath)) || "application/octet-stream";
+    return { kind: "file", mime_type: guessed.toString() };
+}
+function validateArtifactShape(value, index, errors) {
+    if (!isObject(value)) {
+        errors.push(`artifacts[${index}] must be an object`);
+        return false;
+    }
+    const requiredStringFields = ["id", "name", "filename", "kind", "mime_type", "created_at", "updated_at"];
+    for (const field of requiredStringFields) {
+        if (typeof value[field] !== "string" || value[field].length === 0) {
+            errors.push(`artifacts[${index}].${field} must be a non-empty string`);
+        }
+    }
+    if (typeof value.size_bytes !== "number" || Number.isNaN(value.size_bytes) || value.size_bytes < 0) {
+        errors.push(`artifacts[${index}].size_bytes must be a non-negative number`);
+    }
+    if (!Array.isArray(value.tags) || value.tags.some((tag) => typeof tag !== "string")) {
+        errors.push(`artifacts[${index}].tags must be an array of strings`);
+    }
+    if (!isIsoDate(value.created_at)) {
+        errors.push(`artifacts[${index}].created_at must be an ISO timestamp`);
+    }
+    if (!isIsoDate(value.updated_at)) {
+        errors.push(`artifacts[${index}].updated_at must be an ISO timestamp`);
+    }
+    return true;
+}
+export async function validateManifest(manifestPath, artifactsDir) {
+    const errors = [];
+    const warnings = [];
+    let raw;
+    try {
+        raw = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errors: [`manifest read/parse failed: ${String(error)}`],
+            warnings,
+            artifact_count: 0,
+        };
+    }
+    if (!isObject(raw)) {
+        return { ok: false, errors: ["manifest root must be an object"], warnings, artifact_count: 0 };
+    }
+    if (raw.version !== MANIFEST_VERSION) {
+        errors.push(`version must be ${String(MANIFEST_VERSION)}`);
+    }
+    if (!isIsoDate(raw.created_at)) {
+        errors.push("created_at must be an ISO timestamp");
+    }
+    if (!isIsoDate(raw.updated_at)) {
+        errors.push("updated_at must be an ISO timestamp");
+    }
+    if (!Array.isArray(raw.artifacts)) {
+        errors.push("artifacts must be an array");
+    }
+    const artifacts = Array.isArray(raw.artifacts) ? raw.artifacts : [];
+    const seenIds = new Set();
+    const seenFiles = new Set();
+    const kinds = new Set(Object.keys(KIND_EXTENSIONS));
+    for (let index = 0; index < artifacts.length; index += 1) {
+        const item = artifacts[index];
+        if (!validateArtifactShape(item, index, errors))
+            continue;
+        if (seenIds.has(item.id))
+            errors.push(`duplicate artifact id: ${item.id}`);
+        seenIds.add(item.id);
+        if (seenFiles.has(item.filename))
+            errors.push(`duplicate artifact filename: ${item.filename}`);
+        seenFiles.add(item.filename);
+        if (!relativePathSafe(item.filename)) {
+            errors.push(`artifacts[${index}].filename must be a safe relative path`);
+            continue;
+        }
+        if (!kinds.has(item.kind)) {
+            errors.push(`artifacts[${index}].kind must be one of: ${Array.from(kinds).join(", ")}`);
+        }
+        else {
+            const ext = path.extname(item.filename).toLowerCase();
+            const allowed = KIND_EXTENSIONS[item.kind];
+            if (allowed.length > 0 && !allowed.includes(ext)) {
+                errors.push(`artifacts[${index}] kind "${item.kind}" requires one of: ${allowed.join(", ")}`);
+            }
+        }
+        const artifactPath = path.join(artifactsDir, item.filename);
+        const stat = await fs.stat(artifactPath).catch(() => null);
+        if (!stat || !stat.isFile()) {
+            errors.push(`artifacts[${index}] file is missing: ${item.filename}`);
+            continue;
+        }
+        if (stat.size !== item.size_bytes) {
+            warnings.push(`artifacts[${index}] size_bytes (${String(item.size_bytes)}) differs from disk size (${String(stat.size)})`);
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings,
+        artifact_count: artifacts.length,
+    };
+}
+export function isManifest(value) {
+    return isObject(value) && Array.isArray(value.artifacts) && value.version === MANIFEST_VERSION;
+}

package/dist/storage.d.ts

@@ -0,0 +1,38 @@
+import type { Artifact } from "./types.js";
+export declare class ReferencesStore {
+    readonly repoRoot: string;
+    readonly refsDir: string;
+    readonly artifactsDir: string;
+    readonly manifestPath: string;
+    constructor(repoRoot: string);
+    private ensureStructure;
+    private emptyManifest;
+    private readManifest;
+    private writeManifest;
+    listArtifacts(): Promise<Artifact[]>;
+    getArtifact(artifactId: string): Promise<Artifact | null>;
+    getArtifactPath(artifact: Artifact): string;
+    private slugify;
+    private uniqueFilename;
+    createArtifact(input: {
+        name: string;
+        content?: string | null;
+        kind?: string | null;
+        mime_type?: string | null;
+        tags?: string[] | null;
+    }): Promise<Artifact>;
+    reindexArtifacts(): Promise<{
+        added: number;
+        removed: number;
+        total: number;
+    }>;
+    validateManifest(): Promise<import("./manifest.js").ManifestValidationResult>;
+    updateArtifact(artifactId: string, input: {
+        name?: string | null;
+        content?: string | null;
+        kind?: string | null;
+        mime_type?: string | null;
+        tags?: string[] | null;
+    }): Promise<Artifact | null>;
+    deleteArtifact(artifactId: string): Promise<boolean>;
+}

package/dist/storage.js

@@ -0,0 +1,238 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { inferArtifactType, MANIFEST_VERSION, validateManifest } from "./manifest.js";
+function utcNow() {
+    return new Date().toISOString();
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export class ReferencesStore {
+    repoRoot;
+    refsDir;
+    artifactsDir;
+    manifestPath;
+    constructor(repoRoot) {
+        this.repoRoot = repoRoot;
+        this.refsDir = path.join(repoRoot, ".references");
+        this.artifactsDir = path.join(this.refsDir, "artifacts");
+        this.manifestPath = path.join(this.refsDir, "manifest.json");
+        this.ensureStructure();
+    }
+    ensureStructure() {
+        mkdirSync(this.refsDir, { recursive: true });
+        mkdirSync(this.artifactsDir, { recursive: true });
+        void fs.access(this.manifestPath).catch(async () => {
+            await this.writeManifest(this.emptyManifest());
+        });
+    }
+    emptyManifest() {
+        const now = utcNow();
+        return {
+            version: MANIFEST_VERSION,
+            created_at: now,
+            updated_at: now,
+            artifacts: [],
+        };
+    }
+    async readManifest() {
+        let raw;
+        try {
+            const text = await fs.readFile(this.manifestPath, "utf8");
+            raw = JSON.parse(text);
+        }
+        catch {
+            return this.emptyManifest();
+        }
+        if (Array.isArray(raw)) {
+            return {
+                version: 0,
+                created_at: utcNow(),
+                updated_at: utcNow(),
+                artifacts: raw,
+            };
+        }
+        if (!isObject(raw)) {
+            return this.emptyManifest();
+        }
+        const artifacts = Array.isArray(raw.artifacts) ? raw.artifacts : [];
+        return {
+            version: typeof raw.version === "number" ? raw.version : MANIFEST_VERSION,
+            created_at: typeof raw.created_at === "string" ? raw.created_at : utcNow(),
+            updated_at: typeof raw.updated_at === "string" ? raw.updated_at : utcNow(),
+            artifacts,
+        };
+    }
+    async writeManifest(manifest) {
+        await fs.writeFile(this.manifestPath, JSON.stringify(manifest, null, 2));
+    }
+    async listArtifacts() {
+        const manifest = await this.readManifest();
+        return manifest.artifacts;
+    }
+    async getArtifact(artifactId) {
+        const manifest = await this.readManifest();
+        return manifest.artifacts.find((item) => item.id === artifactId) ?? null;
+    }
+    getArtifactPath(artifact) {
+        return path.join(this.artifactsDir, artifact.filename);
+    }
+    slugify(name) {
+        const cleaned = name
+            .split("")
+            .filter((ch) => /[\w\- ]/.test(ch))
+            .join("")
+            .trim()
+            .replace(/\s+/g, "-")
+            .toLowerCase();
+        return cleaned || "untitled";
+    }
+    async uniqueFilename(base, ext = ".md") {
+        let candidate = `${base}${ext}`;
+        let counter = 2;
+        while (true) {
+            try {
+                await fs.access(path.join(this.artifactsDir, candidate));
+                candidate = `${base}-${counter}${ext}`;
+                counter += 1;
+            }
+            catch {
+                return candidate;
+            }
+        }
+    }
+    async createArtifact(input) {
+        const id = randomUUID();
+        const safe = this.slugify(input.name);
+        const filename = await this.uniqueFilename(safe, ".md");
+        const now = utcNow();
+        const artifactPath = path.join(this.artifactsDir, filename);
+        if (input.content !== undefined && input.content !== null) {
+            await fs.writeFile(artifactPath, input.content, "utf8");
+        }
+        let sizeBytes = 0;
+        try {
+            const stat = await fs.stat(artifactPath);
+            sizeBytes = stat.size;
+        }
+        catch {
+            sizeBytes = 0;
+        }
+        const artifact = {
+            id,
+            name: input.name,
+            filename,
+            kind: input.kind ?? "note",
+            mime_type: input.mime_type ?? "text/markdown",
+            size_bytes: sizeBytes,
+            tags: input.tags ?? [],
+            created_at: now,
+            updated_at: now,
+        };
+        const manifest = await this.readManifest();
+        manifest.updated_at = utcNow();
+        manifest.artifacts.push(artifact);
+        await this.writeManifest(manifest);
+        return artifact;
+    }
+    async reindexArtifacts() {
+        const manifest = await this.readManifest();
+        const entries = await fs.readdir(this.artifactsDir, { withFileTypes: true });
+        const filesOnDisk = new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name));
+        const beforeCount = manifest.artifacts.length;
+        manifest.artifacts = manifest.artifacts.filter((artifact) => filesOnDisk.has(artifact.filename));
+        const removed = beforeCount - manifest.artifacts.length;
+        const artifactsByFilename = new Map(manifest.artifacts.map((artifact) => [artifact.filename, artifact]));
+        const known = new Set(manifest.artifacts.map((a) => a.filename));
+        let added = 0;
+        let updated = 0;
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const filePath = path.join(this.artifactsDir, entry.name);
+            const stats = await fs.stat(filePath);
+            const inferred = inferArtifactType(filePath);
+            if (known.has(entry.name)) {
+                const artifact = artifactsByFilename.get(entry.name);
+                if (!artifact)
+                    continue;
+                const previousUpdated = Date.parse(artifact.updated_at);
+                const changedOnDisk = artifact.size_bytes !== stats.size ||
+                    artifact.kind !== inferred.kind ||
+                    artifact.mime_type !== inferred.mime_type ||
+                    Number.isNaN(previousUpdated) ||
+                    previousUpdated < stats.mtimeMs;
+                if (changedOnDisk) {
+                    artifact.size_bytes = stats.size;
+                    artifact.kind = inferred.kind;
+                    artifact.mime_type = inferred.mime_type;
+                    artifact.updated_at = stats.mtime.toISOString();
+                    updated += 1;
+                }
+                continue;
+            }
+            const now = utcNow();
+            const artifact = {
+                id: randomUUID(),
+                name: path.basename(entry.name, path.extname(entry.name)).replace(/-/g, " ").trim() || "untitled",
+                filename: entry.name,
+                kind: inferred.kind,
+                mime_type: inferred.mime_type,
+                size_bytes: stats.size,
+                tags: [],
+                created_at: now,
+                updated_at: now,
+            };
+            manifest.artifacts.push(artifact);
+            added += 1;
+        }
+        if (added > 0 || removed > 0 || updated > 0) {
+            manifest.updated_at = utcNow();
+            await this.writeManifest(manifest);
+        }
+        return { added, removed, total: manifest.artifacts.length };
+    }
+    async validateManifest() {
+        return validateManifest(this.manifestPath, this.artifactsDir);
+    }
+    async updateArtifact(artifactId, input) {
+        const manifest = await this.readManifest();
+        const index = manifest.artifacts.findIndex((item) => item.id === artifactId);
+        if (index === -1)
+            return null;
+        const item = manifest.artifacts[index];
+        if (input.name !== undefined && input.name !== null)
+            item.name = input.name;
+        if (input.kind !== undefined && input.kind !== null)
+            item.kind = input.kind;
+        if (input.mime_type !== undefined && input.mime_type !== null)
+            item.mime_type = input.mime_type;
+        if (input.tags !== undefined && input.tags !== null)
+            item.tags = input.tags;
+        if (input.content !== undefined && input.content !== null) {
+            const artifactPath = this.getArtifactPath(item);
+            await fs.writeFile(artifactPath, input.content, "utf8");
+            const stat = await fs.stat(artifactPath);
+            item.size_bytes = stat.size;
+        }
+        item.updated_at = utcNow();
+        manifest.updated_at = utcNow();
+        manifest.artifacts[index] = item;
+        await this.writeManifest(manifest);
+        return item;
+    }
+    async deleteArtifact(artifactId) {
+        const manifest = await this.readManifest();
+        const index = manifest.artifacts.findIndex((item) => item.id === artifactId);
+        if (index === -1)
+            return false;
+        const [removed] = manifest.artifacts.splice(index, 1);
+        const artifactPath = this.getArtifactPath(removed);
+        await fs.rm(artifactPath, { force: true });
+        manifest.updated_at = utcNow();
+        await this.writeManifest(manifest);
+        return true;
+    }
+}

package/dist/summarize.d.ts

@@ -0,0 +1,17 @@
+import type { Artifact } from "./types.js";
+export interface SuggestedReference {
+    filename: string;
+    reason: string;
+}
+export interface ArtifactSummary {
+    themes: string[];
+    open_questions: string[];
+    candidate_changes: string[];
+    suggested_reffy_references: SuggestedReference[];
+}
+interface StoreReader {
+    listArtifacts(): Promise<Artifact[]>;
+    getArtifactPath(artifact: Artifact): string;
+}
+export declare function summarizeArtifacts(store: StoreReader): Promise<ArtifactSummary>;
+export {};

package/dist/summarize.js

@@ -0,0 +1,107 @@
+import { promises as fs } from "node:fs";
+const GENERIC_HEADINGS = new Set([
+    "problem",
+    "proposed feature",
+    "scope",
+    "scope (small)",
+    "why it fits reffy",
+    "ux sketch",
+    "acceptance criteria",
+    "follow-up",
+    "follow-up (optional)",
+]);
+function normalizeLine(line) {
+    return line.replace(/`/g, "").replace(/\s+/g, " ").trim();
+}
+function pushUnique(list, value) {
+    const next = normalizeLine(value);
+    if (next.length === 0)
+        return;
+    if (!list.includes(next))
+        list.push(next);
+}
+function isLikelyNaturalLanguageQuestion(line) {
+    if (!line.includes("?"))
+        return false;
+    if (/[{}\[\]]/.test(line))
+        return false;
+    if (/["']\s*:/.test(line))
+        return false;
+    return true;
+}
+function headingValue(line) {
+    const match = line.match(/^#{1,6}\s+(.+)$/);
+    if (!match)
+        return null;
+    return normalizeLine(match[1] ?? "");
+}
+function summarizeArtifactContent(artifact, content, themeOut, questionsOut, changesOut) {
+    let currentSection = "";
+    let hasQuestion = false;
+    const lines = content.split(/\r?\n/);
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        const heading = headingValue(line);
+        if (heading) {
+            currentSection = heading.toLowerCase();
+            const generic = GENERIC_HEADINGS.has(currentSection);
+            if (!generic) {
+                const cleaned = heading.replace(/^feature idea:\s*/i, "");
+                pushUnique(themeOut, cleaned);
+            }
+            continue;
+        }
+        if (isLikelyNaturalLanguageQuestion(line)) {
+            hasQuestion = true;
+            pushUnique(questionsOut, line.replace(/^[*-]\s*/, ""));
+        }
+        const commandMatches = line.match(/`(reffy [^`]+)`/g) ?? [];
+        for (const cmd of commandMatches) {
+            const cleanCmd = cmd.replace(/`/g, "");
+            pushUnique(changesOut, `Introduce ${cleanCmd}`);
+        }
+        if (currentSection.includes("proposed feature") && line.startsWith("- ") && !line.includes("`reffy ")) {
+            pushUnique(changesOut, line.replace(/^-+\s*/, ""));
+        }
+    }
+    if (themeOut.length === 0) {
+        pushUnique(themeOut, artifact.name);
+    }
+    if (content.toLowerCase().includes("feature idea")) {
+        return "feature ideation and rationale";
+    }
+    if (hasQuestion) {
+        return "open questions and constraints";
+    }
+    return "exploratory context note";
+}
+export async function summarizeArtifacts(store) {
+    const artifacts = await store.listArtifacts();
+    const themes = [];
+    const openQuestions = [];
+    const candidateChanges = [];
+    const references = [];
+    for (const artifact of artifacts) {
+        const path = store.getArtifactPath(artifact);
+        let content = "";
+        try {
+            content = await fs.readFile(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const reason = summarizeArtifactContent(artifact, content, themes, openQuestions, candidateChanges);
+        references.push({
+            filename: artifact.filename,
+            reason,
+        });
+    }
+    return {
+        themes: themes.slice(0, 8),
+        open_questions: openQuestions.slice(0, 8),
+        candidate_changes: candidateChanges.slice(0, 8),
+        suggested_reffy_references: references,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+export interface Artifact {
+    id: string;
+    name: string;
+    filename: string;
+    kind: string;
+    mime_type: string;
+    size_bytes: number;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+}
+export interface Manifest {
+    version: number;
+    created_at: string;
+    updated_at: string;
+    artifacts: Artifact[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "reffy-cli",
+  "version": "0.4.0",
+  "description": "CLI-first, framework-agnostic references workflow for any repo (TypeScript)",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "reffy": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "dev": "tsx watch src/cli.ts",
+    "check": "tsc --noEmit",
+    "test": "npm run build && vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "mime-types": "^2.1.35",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/mime-types": "^2.1.4",
+    "@types/node": "^24.3.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}