reffy-cli 1.2.1 → 1.3.0

package/README.md

@@ -59,6 +59,23 @@ reffy diagram render --input .reffy/reffyspec/specs/auth/spec.md --format ascii
 reffy diagram render --input .reffy/reffyspec/specs/auth/spec.md --format svg --output .reffy/artifacts/auth-spec.svg
 ```
 
+## Manifest Contract
+
+Reffy keeps workspace metadata in `.reffy/manifest.json`. New managed manifests include both core timestamps and workspace identity:
+
+```json
+{
+  "version": 1,
+  "created_at": "2026-04-18T00:00:00.000Z",
+  "updated_at": "2026-04-18T00:00:00.000Z",
+  "project_id": "my-project",
+  "workspace_name": "my-project",
+  "artifacts": []
+}
+```
+
+Older v1 manifests without `project_id` and `workspace_name` still validate. Running `reffy init` migrates managed manifests by adding those fields with deterministic defaults derived from the repository name.
+
 ## Using Reffy With ReffySpec
 
 A practical pattern is:

package/dist/manifest.d.ts

@@ -1,6 +1,9 @@
 import type { Manifest } from "./types.js";
 export declare const MANIFEST_VERSION = 1;
 export declare function allowedKindExtensions(): Record<string, string[]>;
+export declare function deriveManifestIdentity(repoRoot: string): Required<Pick<Manifest, "project_id" | "workspace_name">>;
+export declare function createManifest(repoRoot: string, now?: string): Manifest;
+export declare function normalizeManifest(raw: unknown, repoRoot: string): Manifest;
 export declare function inferArtifactType(filePath: string): {
     kind: string;
     mime_type: string;

package/dist/manifest.js

@@ -12,6 +12,8 @@ const KIND_EXTENSIONS = {
     doc: [".doc", ".docx"],
     file: [],
 };
+const PROJECT_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const FALLBACK_WORKSPACE_ID = "reffy-workspace";
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -20,6 +22,21 @@ function isIsoDate(value) {
         return false;
     return !Number.isNaN(Date.parse(value));
 }
+function isProjectId(value) {
+    return typeof value === "string" && PROJECT_ID_PATTERN.test(value);
+}
+function isWorkspaceName(value) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        !/[\\/\r\n\t]/.test(value));
+}
+function slugifyIdentity(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
 function relativePathSafe(filename) {
     if (path.isAbsolute(filename))
         return false;
@@ -29,6 +46,48 @@ function relativePathSafe(filename) {
 export function allowedKindExtensions() {
     return Object.fromEntries(Object.entries(KIND_EXTENSIONS).map(([kind, extensions]) => [kind, [...extensions]]));
 }
+export function deriveManifestIdentity(repoRoot) {
+    const candidate = slugifyIdentity(path.basename(path.resolve(repoRoot)));
+    const identity = candidate || FALLBACK_WORKSPACE_ID;
+    return {
+        project_id: identity,
+        workspace_name: identity,
+    };
+}
+export function createManifest(repoRoot, now = new Date().toISOString()) {
+    return {
+        version: MANIFEST_VERSION,
+        created_at: now,
+        updated_at: now,
+        ...deriveManifestIdentity(repoRoot),
+        artifacts: [],
+    };
+}
+export function normalizeManifest(raw, repoRoot) {
+    const now = new Date().toISOString();
+    const defaults = deriveManifestIdentity(repoRoot);
+    if (Array.isArray(raw)) {
+        return {
+            version: 0,
+            created_at: now,
+            updated_at: now,
+            ...defaults,
+            artifacts: raw,
+        };
+    }
+    if (!isObject(raw)) {
+        return createManifest(repoRoot, now);
+    }
+    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 : now,
+        updated_at: typeof raw.updated_at === "string" ? raw.updated_at : now,
+        project_id: typeof raw.project_id === "string" ? raw.project_id : defaults.project_id,
+        workspace_name: typeof raw.workspace_name === "string" ? raw.workspace_name : defaults.workspace_name,
+        artifacts,
+    };
+}
 export function inferArtifactType(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     if (ext === ".excalidraw")
@@ -121,6 +180,12 @@ export async function validateManifest(manifestPath, artifactsDir) {
     if (!isIsoDate(raw.updated_at)) {
         errors.push("updated_at must be an ISO timestamp");
     }
+    if (raw.project_id !== undefined && !isProjectId(raw.project_id)) {
+        errors.push("project_id must be a non-empty kebab-case string");
+    }
+    if (raw.workspace_name !== undefined && !isWorkspaceName(raw.workspace_name)) {
+        errors.push("workspace_name must be a non-empty string without path separators or control characters");
+    }
     if (!Array.isArray(raw.artifacts)) {
         errors.push("artifacts must be an array");
     }

package/dist/storage.d.ts

@@ -10,6 +10,10 @@ export declare class ReferencesStore {
     private readManifest;
     private writeManifest;
     listArtifacts(): Promise<Artifact[]>;
+    getWorkspaceIdentity(): Promise<{
+        project_id?: string;
+        workspace_name?: string;
+    }>;
     getArtifact(artifactId: string): Promise<Artifact | null>;
     getArtifactPath(artifact: Artifact): string;
     private slugify;

package/dist/storage.js

@@ -2,14 +2,11 @@ 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";
+import { createManifest, inferArtifactType, normalizeManifest, validateManifest } from "./manifest.js";
 import { resolveRefsDir } from "./refs-paths.js";
 function utcNow() {
     return new Date().toISOString();
 }
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 export class ReferencesStore {
     repoRoot;
     refsDir;
@@ -30,13 +27,7 @@ export class ReferencesStore {
         });
     }
     emptyManifest() {
-        const now = utcNow();
-        return {
-            version: MANIFEST_VERSION,
-            created_at: now,
-            updated_at: now,
-            artifacts: [],
-        };
+        return createManifest(this.repoRoot, utcNow());
     }
     async readManifest() {
         let raw;
@@ -47,24 +38,7 @@ export class ReferencesStore {
         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,
-        };
+        return normalizeManifest(raw, this.repoRoot);
     }
     async writeManifest(manifest) {
         await fs.writeFile(this.manifestPath, JSON.stringify(manifest, null, 2));
@@ -73,6 +47,13 @@ export class ReferencesStore {
         const manifest = await this.readManifest();
         return manifest.artifacts;
     }
+    async getWorkspaceIdentity() {
+        const manifest = await this.readManifest();
+        return {
+            project_id: manifest.project_id,
+            workspace_name: manifest.workspace_name,
+        };
+    }
     async getArtifact(artifactId) {
         const manifest = await this.readManifest();
         return manifest.artifacts.find((item) => item.id === artifactId) ?? null;

package/dist/types.d.ts

@@ -16,5 +16,7 @@ export interface Manifest {
     version: number;
     created_at: string;
     updated_at: string;
+    project_id?: string;
+    workspace_name?: string;
     artifacts: Artifact[];
 }

package/dist/workspace.js

@@ -1,5 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { deriveManifestIdentity, normalizeManifest } from "./manifest.js";
 import { DEFAULT_REFS_DIRNAME, LEGACY_REFS_DIRNAME, detectWorkspaceState, resolveCanonicalRefsDir, } from "./refs-paths.js";
 async function pathExists(targetPath) {
     try {
@@ -20,13 +21,28 @@ async function ensureCanonicalStructure(repoRoot) {
     }
     await fs.mkdir(artifactsDir, { recursive: true });
     if (!(await pathExists(manifestPath))) {
-        const now = new Date().toISOString();
-        await fs.writeFile(manifestPath, JSON.stringify({
-            version: 1,
-            created_at: now,
-            updated_at: now,
-            artifacts: [],
-        }, null, 2), "utf8");
+        await fs.writeFile(manifestPath, JSON.stringify(normalizeManifest(undefined, repoRoot), null, 2), "utf8");
+    }
+    else {
+        const rawText = await fs.readFile(manifestPath, "utf8").catch(() => null);
+        if (rawText) {
+            try {
+                const raw = JSON.parse(rawText);
+                if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+                    const record = raw;
+                    const defaults = deriveManifestIdentity(repoRoot);
+                    const missingIdentity = record.project_id === undefined || record.workspace_name === undefined;
+                    if (missingIdentity) {
+                        const nextManifest = normalizeManifest(raw, repoRoot);
+                        nextManifest.updated_at = new Date().toISOString();
+                        await fs.writeFile(manifestPath, JSON.stringify(nextManifest, null, 2), "utf8");
+                    }
+                }
+            }
+            catch {
+                // Leave invalid manifests untouched so validation can report the problem explicitly.
+            }
+        }
     }
     return created;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Planning system for AI assisted development.",
   "keywords": [
     "reffy",