reffy-cli 0.6.5 → 0.6.7

package/README.md

@@ -23,11 +23,11 @@ reffy bootstrap
 
 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 init`: idempotently creates/updates root `AGENTS.md` managed block and `.reffy/AGENTS.md`.
+- `reffy bootstrap`: idempotently runs `init`, ensures `.reffy/` 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 reindex`: reconciles `.reffy/manifest.json` with `.reffy/artifacts` by adding missing files and removing stale entries.
+- `reffy validate`: validates `.reffy/manifest.json` against manifest v1 contract.
 - `reffy summarize`: generates a read-only handoff summary from indexed artifacts.
 - `reffy diagram render`: renders Mermaid diagrams as SVG or ASCII, including spec-aware generation from OpenSpec `spec.md`.
 
@@ -48,31 +48,31 @@ reffy summarize --output text
 reffy summarize --output json
 reffy diagram render --stdin --format svg < diagram.mmd
 reffy diagram render --input openspec/specs/auth/spec.md --format ascii
-reffy diagram render --input openspec/specs/auth/spec.md --format svg --output .references/artifacts/auth-spec.svg
+reffy diagram render --input openspec/specs/auth/spec.md --format svg --output .reffy/artifacts/auth-spec.svg
 ```
 
 ## 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/`.
+1. Use Reffy for ideation and context capture in `.reffy/`.
 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`: Reffy block routes ideation/exploration requests to `@/.reffy/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.
+- `.reffy/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`.
+- `src/cli.ts`: `reffy init`/`reffy bootstrap` enforce this integration by idempotently writing the managed Reffy guidance into `AGENTS.md` and `.reffy/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.
+3. During planning, cite only relevant Reffy artifacts from `.reffy/artifacts/` in your proposal/spec docs.
 4. Continue implementation in your SDD framework's normal review/approval process.
 
 ## Develop

package/dist/cli.js

@@ -1,10 +1,13 @@
 #!/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 { ReferencesStore } from "./storage.js";
 import { summarizeArtifacts } from "./summarize.js";
+const require = createRequire(import.meta.url);
+const { version: packageVersion } = require("../package.json");
 const REFFY_ASCII = [
     "            __  __      ",
     " _ __ ___  / _|/ _|_   _",
@@ -18,20 +21,20 @@ const REFFY_BLOCK = `<!-- REFFY:START -->
 
 These instructions are for AI assistants working in this project.
 
-Always open \`@/.references/AGENTS.md\` when the request:
+Always open \`@/.reffy/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:
+Use \`@/.reffy/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/\`
+- How to store and consume ideation context in \`.reffy/\`
 
 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_RELATIVE = path.join(".reffy", "AGENTS.md");
 const REFFY_AGENTS_CONTENT = `# Reffy Instructions
 
 These instructions are for AI assistants working in this project.
@@ -39,7 +42,7 @@ 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/\`.
+- If needed, read existing context in \`.reffy/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 +63,9 @@ You can skip Reffy when the request is:
 
 ## Reffy Workflow
 
-1. Read existing artifacts in \`.references/artifacts/\`.
+1. Read existing artifacts in \`.reffy/artifacts/\`.
 2. Add or update artifacts to capture exploratory context.
-3. Run \`reffy reindex\` to index newly added files into \`.references/manifest.json\`.
+3. Run \`reffy reindex\` to index newly added files into \`.reffy/manifest.json\`.
 4. Run \`reffy validate\` to verify manifest contract compliance.
 
 ## Relationship To OpenSpec
@@ -102,7 +105,7 @@ No Reffy references used.
 
 ## Artifact Conventions
 
-- Treat \`.references/\` as a repository-local guidance and ideation context layer.
+- Treat \`.reffy/\` 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).
@@ -153,10 +156,10 @@ function isDirectory(targetPath) {
 function discoverRepoRoot(startDir) {
     let current = path.resolve(startDir);
     while (true) {
-        if (path.basename(current) === ".references" && isDirectory(path.join(current, "artifacts"))) {
+        if (path.basename(current) === ".reffy" && isDirectory(path.join(current, "artifacts"))) {
             return path.dirname(current);
         }
-        if (isDirectory(path.join(current, ".references"))) {
+        if (isDirectory(path.join(current, ".reffy"))) {
             return current;
         }
         if (pathExists(path.join(current, "AGENTS.md")) || pathExists(path.join(current, ".git"))) {
@@ -224,12 +227,15 @@ 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 .references/AGENTS.md are up to date.",
-        "  bootstrap  Run init, ensure .references structure exists, then reindex artifacts.",
+        "  init       Ensure root AGENTS.md block and .reffy/AGENTS.md are up to date.",
+        "  bootstrap  Run init, ensure .reffy 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.",
+        "  reindex    Scan .reffy/artifacts and add missing files to manifest.",
+        "  validate   Validate .reffy/manifest.json against manifest v1 contract.",
         "  summarize  Generate a read-only summary of indexed Reffy artifacts.",
         "  diagram    Render Mermaid diagrams (supports SVG and ASCII).",
     ].join("\n");
@@ -365,9 +371,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

@@ -27,7 +27,7 @@ function summarizeChecks(checks) {
 }
 export async function runDoctor(repoRoot, options) {
     const checks = [];
-    const refsDir = path.join(repoRoot, ".references");
+    const refsDir = path.join(repoRoot, ".reffy");
     const artifactsDir = path.join(refsDir, "artifacts");
     const manifestPath = path.join(refsDir, "manifest.json");
     const rootAgentsPath = path.join(repoRoot, "AGENTS.md");
@@ -37,14 +37,14 @@ export async function runDoctor(repoRoot, options) {
         id: "refs_dir_exists",
         level: "required",
         ok: refsDirExists,
-        message: refsDirExists ? ".references directory found" : ".references directory is missing",
+        message: refsDirExists ? ".reffy directory found" : ".reffy 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",
+        message: artifactsDirExists ? ".reffy/artifacts directory found" : ".reffy/artifacts directory is missing",
     });
     const rootAgentsExists = await pathExists(rootAgentsPath);
     checks.push({
@@ -58,7 +58,7 @@ export async function runDoctor(repoRoot, options) {
         id: "refs_agents_exists",
         level: "required",
         ok: refsAgentsExists,
-        message: refsAgentsExists ? ".references/AGENTS.md found" : ".references/AGENTS.md is missing",
+        message: refsAgentsExists ? ".reffy/AGENTS.md found" : ".reffy/AGENTS.md is missing",
     });
     const manifestExists = await pathExists(manifestPath);
     if (!manifestExists) {
@@ -66,7 +66,7 @@ export async function runDoctor(repoRoot, options) {
             id: "manifest_valid",
             level: "required",
             ok: false,
-            message: ".references/manifest.json is missing",
+            message: ".reffy/manifest.json is missing",
         });
     }
     else {
@@ -76,7 +76,7 @@ export async function runDoctor(repoRoot, options) {
             level: "required",
             ok: manifestResult.ok,
             message: manifestResult.ok
-                ? `.references/manifest.json is valid (artifacts=${String(manifestResult.artifact_count)})`
+                ? `.reffy/manifest.json is valid (artifacts=${String(manifestResult.artifact_count)})`
                 : `manifest invalid: ${manifestResult.errors.join("; ")}`,
         });
     }

package/dist/storage.js

@@ -16,7 +16,7 @@ export class ReferencesStore {
     manifestPath;
     constructor(repoRoot) {
         this.repoRoot = repoRoot;
-        this.refsDir = path.join(repoRoot, ".references");
+        this.refsDir = path.join(repoRoot, ".reffy");
         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.5",
+  "version": "0.6.7",
   "description": "CLI-first, framework-agnostic references workflow for any repo (TypeScript)",
   "keywords": [
     "reffy",