reffy-cli 0.6.6 → 0.7.0

package/dist/cli.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { existsSync, promises as fs, statSync } from "node:fs";
 import path from "node:path";
 import { renderDiagram } from "./diagram.js";
 import { runDoctor } from "./doctor.js";
+import { DEFAULT_REFS_DIRNAME, looksLikeRefsDir, resolveRefsDirName } from "./refs-paths.js";
 import { ReferencesStore } from "./storage.js";
 import { summarizeArtifacts } from "./summarize.js";
+const require = createRequire(import.meta.url);
+const { version: packageVersion } = require("../package.json");
 const REFFY_ASCII = [
     "            __  __      ",
     " _ __ ___  / _|/ _|_   _",
@@ -13,33 +17,35 @@ const REFFY_ASCII = [
     "|_|  \\___||_| |_|  \\__, |",
     "                   |___/ ",
 ].join("\n");
-const REFFY_BLOCK = `<!-- REFFY:START -->
+function buildReffyBlock(refsDirName) {
+    return `<!-- REFFY:START -->
 # Reffy Instructions
 
 These instructions are for AI assistants working in this project.
 
-Always open \`@/.reffy/AGENTS.md\` when the request:
+Always open \`@/${refsDirName}/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 \`@/.reffy/AGENTS.md\` to learn:
+Use \`@/${refsDirName}/AGENTS.md\` to learn:
 - Reffy workflow and artifact conventions
 - How Reffy and OpenSpec should be sequenced
-- How to store and consume ideation context in \`.reffy/\`
+- How to store and consume ideation context in \`${refsDirName}/\`
 
 Keep this managed block so \`reffy init\` can refresh the instructions.
 
 <!-- REFFY:END -->`;
-const REFFY_AGENTS_RELATIVE = path.join(".reffy", "AGENTS.md");
-const REFFY_AGENTS_CONTENT = `# Reffy Instructions
+}
+function buildReffyAgentsContent(refsDirName) {
+    return `# 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 \`.reffy/artifacts/\`.
+- If needed, read existing context in \`${refsDirName}/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.
@@ -60,9 +66,9 @@ You can skip Reffy when the request is:
 
 ## Reffy Workflow
 
-1. Read existing artifacts in \`.reffy/artifacts/\`.
+1. Read existing artifacts in \`${refsDirName}/artifacts/\`.
 2. Add or update artifacts to capture exploratory context.
-3. Run \`reffy reindex\` to index newly added files into \`.reffy/manifest.json\`.
+3. Run \`reffy reindex\` to index newly added files into \`${refsDirName}/manifest.json\`.
 4. Run \`reffy validate\` to verify manifest contract compliance.
 
 ## Relationship To OpenSpec
@@ -102,30 +108,36 @@ No Reffy references used.
 
 ## Artifact Conventions
 
-- Treat \`.reffy/\` as a repository-local guidance and ideation context layer.
+- Treat \`${refsDirName}/\` 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) {
+    return upsertReffyBlockForDir(content, DEFAULT_REFS_DIRNAME);
+}
+function upsertReffyBlockForDir(content, refsDirName) {
+    const reffyBlock = buildReffyBlock(refsDirName);
     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`;
+        return trimmedSuffix.length > 0 ? `${prefix}${reffyBlock}\n\n${trimmedSuffix}` : `${prefix}${reffyBlock}\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 `${before.trimEnd()}\n\n${reffyBlock}\n\n${OPENSPEC_START}${after}`;
     }
-    return content.trim().length > 0 ? `${REFFY_BLOCK}\n\n${content.trimStart()}` : `${REFFY_BLOCK}\n`;
+    return content.trim().length > 0 ? `${reffyBlock}\n\n${content.trimStart()}` : `${reffyBlock}\n`;
 }
 async function initAgents(repoRoot) {
+    const refsDirName = resolveRefsDirName(repoRoot);
     const agentsPath = path.join(repoRoot, "AGENTS.md");
-    const reffyAgentsPath = path.join(repoRoot, REFFY_AGENTS_RELATIVE);
+    const reffyAgentsPath = path.join(repoRoot, refsDirName, "AGENTS.md");
     let content = "";
     try {
         content = await fs.readFile(agentsPath, "utf8");
@@ -133,10 +145,10 @@ async function initAgents(repoRoot) {
     catch {
         content = "";
     }
-    const updated = upsertReffyBlock(content);
+    const updated = upsertReffyBlockForDir(content, refsDirName);
     await fs.mkdir(path.dirname(reffyAgentsPath), { recursive: true });
     await fs.writeFile(agentsPath, updated, "utf8");
-    await fs.writeFile(reffyAgentsPath, REFFY_AGENTS_CONTENT, "utf8");
+    await fs.writeFile(reffyAgentsPath, buildReffyAgentsContent(refsDirName), "utf8");
     return { root_agents_path: agentsPath, reffy_agents_path: reffyAgentsPath };
 }
 function pathExists(targetPath) {
@@ -153,10 +165,10 @@ function isDirectory(targetPath) {
 function discoverRepoRoot(startDir) {
     let current = path.resolve(startDir);
     while (true) {
-        if (path.basename(current) === ".reffy" && isDirectory(path.join(current, "artifacts"))) {
+        if (looksLikeRefsDir(current)) {
             return path.dirname(current);
         }
-        if (isDirectory(path.join(current, ".reffy"))) {
+        if (isDirectory(path.join(current, DEFAULT_REFS_DIRNAME)) || isDirectory(path.join(current, ".references"))) {
             return current;
         }
         if (pathExists(path.join(current, "AGENTS.md")) || pathExists(path.join(current, ".git"))) {
@@ -224,6 +236,9 @@ function usage() {
     return [
         "Usage: reffy <command> [--repo PATH] [--output text|json]",
         "",
+        "Flags:",
+        "  --version  Print the installed reffy package version.",
+        "",
         "Commands:",
         "  init       Ensure root AGENTS.md block and .reffy/AGENTS.md are up to date.",
         "  bootstrap  Run init, ensure .reffy structure exists, then reindex artifacts.",
@@ -365,9 +380,13 @@ function printSection(title, values) {
 }
 async function main() {
     const [, , command, ...rest] = process.argv;
-    if (!command) {
+    if (!command || command === "--help" || command === "-h") {
         console.error(usage());
-        return 1;
+        return command ? 0 : 1;
+    }
+    if (command === "--version") {
+        console.log(packageVersion);
+        return 0;
     }
     if (command === "diagram") {
         const [subcommand, ...diagramArgs] = rest;

package/dist/doctor.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { validateManifest } from "./manifest.js";
+import { resolveRefsDirName } from "./refs-paths.js";
 async function pathExists(targetPath) {
     try {
         await fs.access(targetPath);
@@ -27,7 +28,8 @@ function summarizeChecks(checks) {
 }
 export async function runDoctor(repoRoot, options) {
     const checks = [];
-    const refsDir = path.join(repoRoot, ".reffy");
+    const refsDirName = resolveRefsDirName(repoRoot);
+    const refsDir = path.join(repoRoot, refsDirName);
     const artifactsDir = path.join(refsDir, "artifacts");
     const manifestPath = path.join(refsDir, "manifest.json");
     const rootAgentsPath = path.join(repoRoot, "AGENTS.md");
@@ -37,14 +39,16 @@ export async function runDoctor(repoRoot, options) {
         id: "refs_dir_exists",
         level: "required",
         ok: refsDirExists,
-        message: refsDirExists ? ".reffy directory found" : ".reffy directory is missing",
+        message: refsDirExists ? `${refsDirName} directory found` : `${refsDirName} directory is missing`,
     });
     const artifactsDirExists = await pathExists(artifactsDir);
     checks.push({
         id: "artifacts_dir_exists",
         level: "required",
         ok: artifactsDirExists,
-        message: artifactsDirExists ? ".reffy/artifacts directory found" : ".reffy/artifacts directory is missing",
+        message: artifactsDirExists
+            ? `${refsDirName}/artifacts directory found`
+            : `${refsDirName}/artifacts directory is missing`,
     });
     const rootAgentsExists = await pathExists(rootAgentsPath);
     checks.push({
@@ -58,7 +62,7 @@ export async function runDoctor(repoRoot, options) {
         id: "refs_agents_exists",
         level: "required",
         ok: refsAgentsExists,
-        message: refsAgentsExists ? ".reffy/AGENTS.md found" : ".reffy/AGENTS.md is missing",
+        message: refsAgentsExists ? `${refsDirName}/AGENTS.md found` : `${refsDirName}/AGENTS.md is missing`,
     });
     const manifestExists = await pathExists(manifestPath);
     if (!manifestExists) {
@@ -66,7 +70,7 @@ export async function runDoctor(repoRoot, options) {
             id: "manifest_valid",
             level: "required",
             ok: false,
-            message: ".reffy/manifest.json is missing",
+            message: `${refsDirName}/manifest.json is missing`,
         });
     }
     else {
@@ -76,7 +80,7 @@ export async function runDoctor(repoRoot, options) {
             level: "required",
             ok: manifestResult.ok,
             message: manifestResult.ok
-                ? `.reffy/manifest.json is valid (artifacts=${String(manifestResult.artifact_count)})`
+                ? `${refsDirName}/manifest.json is valid (artifacts=${String(manifestResult.artifact_count)})`
                 : `manifest invalid: ${manifestResult.errors.join("; ")}`,
         });
     }

package/dist/refs-paths.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_REFS_DIRNAME = ".reffy";
+export declare const LEGACY_REFS_DIRNAME = ".references";
+export declare function resolveRefsDirName(repoRoot: string): string;
+export declare function resolveRefsDir(repoRoot: string): string;
+export declare function looksLikeRefsDir(targetPath: string): boolean;

package/dist/refs-paths.js

@@ -0,0 +1,32 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+export const DEFAULT_REFS_DIRNAME = ".reffy";
+export const LEGACY_REFS_DIRNAME = ".references";
+function isDirectory(targetPath) {
+    try {
+        return statSync(targetPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveRefsDirName(repoRoot) {
+    const reffyDir = path.join(repoRoot, DEFAULT_REFS_DIRNAME);
+    if (isDirectory(reffyDir)) {
+        return DEFAULT_REFS_DIRNAME;
+    }
+    const legacyDir = path.join(repoRoot, LEGACY_REFS_DIRNAME);
+    if (isDirectory(legacyDir)) {
+        return LEGACY_REFS_DIRNAME;
+    }
+    return DEFAULT_REFS_DIRNAME;
+}
+export function resolveRefsDir(repoRoot) {
+    return path.join(repoRoot, resolveRefsDirName(repoRoot));
+}
+export function looksLikeRefsDir(targetPath) {
+    const base = path.basename(targetPath);
+    return ((base === DEFAULT_REFS_DIRNAME || base === LEGACY_REFS_DIRNAME) &&
+        existsSync(path.join(targetPath, "artifacts")) &&
+        isDirectory(path.join(targetPath, "artifacts")));
+}

package/dist/storage.js

@@ -3,6 +3,7 @@ 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";
+import { resolveRefsDir } from "./refs-paths.js";
 function utcNow() {
     return new Date().toISOString();
 }
@@ -16,7 +17,7 @@ export class ReferencesStore {
     manifestPath;
     constructor(repoRoot) {
         this.repoRoot = repoRoot;
-        this.refsDir = path.join(repoRoot, ".reffy");
+        this.refsDir = resolveRefsDir(repoRoot);
         this.artifactsDir = path.join(this.refsDir, "artifacts");
         this.manifestPath = path.join(this.refsDir, "manifest.json");
         this.ensureStructure();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "CLI-first, framework-agnostic references workflow for any repo (TypeScript)",
   "keywords": [
     "reffy",