reffy-cli 1.4.0 → 1.4.2

package/README.md

@@ -99,8 +99,8 @@ The current remote flow is:
 1. Reffy reads `project_id` and `workspace_name` from `.reffy/manifest.json`.
 2. Reffy connects to Paseo using `PASEO_ENDPOINT` or `--endpoint`.
 3. `reffy remote init --provision` creates a pod and actor when needed, then writes local linkage state to `.reffy/state/remote.json`.
-4. `reffy remote push` publishes the local workspace to that linked actor.
-5. `reffy remote status|ls|cat` inspects the linked remote workspace.
+4. `reffy remote push` publishes the local workspace to that linked actor with `replace_missing=true` by default, so remote reflects local.
+5. `reffy remote status|ls|cat` inspects the linked remote workspace using the saved linkage state unless you override it.
 
 ### Minimal connection requirement
 
@@ -141,6 +141,8 @@ That file contains the connection tuple Reffy uses to reach the backend:
 
 This file is local runtime state. It is not part of the synced remote workspace and is intentionally excluded from `reffy remote push`.
 
+The file can also record local sync metadata such as the last successful import timestamp. That metadata is for local diagnostics and does not become part of the remote workspace contract.
+
 ### Example flow
 
 ```bash
@@ -152,6 +154,23 @@ reffy remote ls
 reffy remote cat .reffy/manifest.json
 ```
 
+`reffy remote status` is the primary diagnostic command for this flow. It reports:
+
+- the saved linkage being used
+- the local manifest identity
+- the remote workspace identity
+- remote document counts when reachable
+
+`reffy remote push` reports:
+
+- local document count
+- imported count
+- created count
+- updated count
+- deleted count
+
+That makes the default prune/import behavior auditable without dropping to direct backend API calls.
+
 ## Manifest Contract
 
 Reffy keeps workspace metadata in `.reffy/manifest.json`. New managed manifests include both core timestamps and workspace identity:

package/dist/cli.js

@@ -5,11 +5,12 @@ import path from "node:path";
 import { renderDiagram } from "./diagram.js";
 import { runDoctor } from "./doctor.js";
 import { loadDotEnvIfPresent } from "./env.js";
+import { ensureGitignoreEntries } from "./gitignore.js";
 import { archivePlanningChange } from "./plan-archive.js";
 import { createPlanScaffold } from "./plan.js";
 import { DEFAULT_PLANNING_RELATIVE_DIR, looksLikePlanningDir, resolveCanonicalPlanningPath } from "./planning-paths.js";
 import { listPlanningChanges, showPlanningChange, validatePlanningChange } from "./plan-runtime.js";
-import { assertRemoteIdentity, collectWorkspaceDocuments, ensureRemoteInit, extractWorkspaceIdentity, mergeRemoteConfig, PaseoRemoteClient, readRemoteConfig, requireWorkspaceIdentity, resolveRemoteConfigPath, } from "./remote.js";
+import { assertRemoteIdentity, collectWorkspaceDocuments, describeRemoteLinkage, ensureRemoteInit, extractWorkspaceIdentity, mergeRemoteConfig, PaseoRemoteClient, readRemoteConfig, requireWorkspaceIdentity, resolveRemoteConfigPath, updateRemoteConfigMetadata, validateImportResult, } from "./remote.js";
 import { DEFAULT_REFS_DIRNAME, detectWorkspaceState, looksLikeRefsDir } from "./refs-paths.js";
 import { prepareCanonicalPlanningLayout } from "./planning-workspace.js";
 import { ReferencesStore } from "./storage.js";
@@ -813,17 +814,25 @@ async function resolveRemoteContext(args) {
     const store = new ReferencesStore(args.repoRoot);
     const identity = requireWorkspaceIdentity(await store.getWorkspaceIdentity());
     const savedConfig = await readRemoteConfig(args.repoRoot);
-    const mergedConfig = mergeRemoteConfig(savedConfig, {
+    const overrideValues = {
         endpoint: args.endpoint ?? process.env.PASEO_ENDPOINT,
         pod_name: args.podName ?? process.env.PASEO_POD_NAME,
         actor_id: args.actorId ?? process.env.PASEO_ACTOR_ID,
-    });
+    };
+    const mergedConfig = mergeRemoteConfig(savedConfig, overrideValues);
+    const hasOverrides = Boolean(overrideValues.endpoint || overrideValues.pod_name || overrideValues.actor_id);
+    const linkageSource = mergedConfig
+        ? savedConfig && !hasOverrides
+            ? "saved_config"
+            : "cli_or_env_overrides"
+        : "unconfigured";
     return {
         store,
         identity,
         configPath: resolveRemoteConfigPath(args.repoRoot),
         savedConfig,
         mergedConfig,
+        linkageSource,
     };
 }
 async function main() {
@@ -885,7 +894,7 @@ async function main() {
         const parsed = parseRemoteArgs(remoteArgs);
         try {
             if (subcommand === "init") {
-                const { identity } = await resolveRemoteContext(parsed);
+                const { identity, configPath } = await resolveRemoteContext(parsed);
                 const endpoint = parsed.endpoint ?? process.env.PASEO_ENDPOINT;
                 if (!endpoint) {
                     throw new Error("Remote init requires --endpoint or PASEO_ENDPOINT (optionally loaded from .env)");
@@ -897,12 +906,13 @@ async function main() {
                     provision: parsed.provision,
                     identity,
                 });
+                const gitignore = await ensureGitignoreEntries(parsed.repoRoot, [".reffy/state/"]);
                 const payload = {
                     status: "ok",
                     command: "remote",
                     subcommand: "init",
                     provider: result.config.provider,
-                    config_path: resolveRemoteConfigPath(parsed.repoRoot),
+                    config_path: configPath,
                     endpoint: result.config.endpoint,
                     pod_name: result.config.pod_name,
                     actor_id: result.config.actor_id,
@@ -910,6 +920,9 @@ async function main() {
                     created_actor: result.created_actor,
                     project_id: identity.project_id,
                     workspace_name: identity.workspace_name,
+                    linkage_mode: result.created_pod || result.created_actor ? "provisioned" : "existing",
+                    gitignore_path: gitignore.path,
+                    gitignore_added: gitignore.added,
                 };
                 if (output === "json") {
                     printResult(output, payload);
@@ -924,6 +937,10 @@ async function main() {
                     console.log(`Workspace name: ${payload.workspace_name}`);
                     console.log(`Created pod: ${payload.created_pod ? "yes" : "no"}`);
                     console.log(`Created actor: ${payload.created_actor ? "yes" : "no"}`);
+                    console.log(`Linkage mode: ${payload.linkage_mode}`);
+                    if (payload.gitignore_added.length > 0) {
+                        console.log(`Updated .gitignore: ${payload.gitignore_added.join(", ")}`);
+                    }
                 }
                 return 0;
             }
@@ -933,7 +950,14 @@ async function main() {
             }
             const client = new PaseoRemoteClient(context.mergedConfig);
             if (subcommand === "status") {
-                const workspace = await client.getWorkspace();
+                let workspace;
+                try {
+                    workspace = await client.getWorkspace();
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Remote status failed using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                }
                 assertRemoteIdentity(workspace, context.identity);
                 const remoteIdentity = extractWorkspaceIdentity(workspace);
                 const payload = {
@@ -945,12 +969,14 @@ async function main() {
                     endpoint: context.mergedConfig.endpoint,
                     pod_name: context.mergedConfig.pod_name,
                     actor_id: context.mergedConfig.actor_id,
+                    linkage_source: context.linkageSource,
                     local_identity: context.identity,
                     remote_identity: {
                         project_id: remoteIdentity.project_id,
                         workspace_name: remoteIdentity.workspace_name,
                     },
                     document_count: remoteIdentity.document_count,
+                    last_imported_at: context.savedConfig?.last_imported_at ?? null,
                     workspace,
                 };
                 if (output === "json") {
@@ -962,17 +988,35 @@ async function main() {
                     console.log(`Endpoint: ${payload.endpoint}`);
                     console.log(`Pod: ${payload.pod_name}`);
                     console.log(`Actor: ${payload.actor_id}`);
+                    console.log(`Linkage source: ${payload.linkage_source}`);
                     console.log(`Local identity: ${payload.local_identity.project_id}/${payload.local_identity.workspace_name}`);
                     console.log(`Remote identity: ${String(payload.remote_identity.project_id)}/${String(payload.remote_identity.workspace_name)}`);
                     console.log(`Remote document count: ${String(payload.document_count ?? "unknown")}`);
+                    console.log(`Last imported at: ${String(payload.last_imported_at ?? "never")}`);
                 }
                 return 0;
             }
             if (subcommand === "push") {
                 const documents = await collectWorkspaceDocuments(parsed.repoRoot);
-                const importResult = await client.importWorkspace(documents, true);
-                const workspace = await client.getWorkspace();
+                let importResult;
+                try {
+                    importResult = validateImportResult(await client.importWorkspace(documents, true));
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Remote push failed using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                }
+                let workspace;
+                try {
+                    workspace = await client.getWorkspace();
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Remote push could not verify remote state using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                }
                 assertRemoteIdentity(workspace, context.identity);
+                const importedAt = new Date().toISOString();
+                await updateRemoteConfigMetadata(parsed.repoRoot, { last_imported_at: importedAt });
                 const payload = {
                     status: "ok",
                     command: "remote",
@@ -980,13 +1024,16 @@ async function main() {
                     endpoint: context.mergedConfig.endpoint,
                     pod_name: context.mergedConfig.pod_name,
                     actor_id: context.mergedConfig.actor_id,
+                    linkage_source: context.linkageSource,
                     project_id: context.identity.project_id,
                     workspace_name: context.identity.workspace_name,
                     local_document_count: documents.length,
-                    imported: importResult.imported ?? null,
-                    created: importResult.created ?? null,
-                    updated: importResult.updated ?? null,
-                    deleted: importResult.deleted ?? null,
+                    imported: importResult.imported,
+                    created: importResult.created,
+                    updated: importResult.updated,
+                    deleted: importResult.deleted,
+                    replace_missing: true,
+                    last_imported_at: importedAt,
                     remote_document_count: extractWorkspaceIdentity(workspace).document_count,
                 };
                 if (output === "json") {
@@ -997,17 +1044,27 @@ async function main() {
                     console.log(`Endpoint: ${payload.endpoint}`);
                     console.log(`Pod: ${payload.pod_name}`);
                     console.log(`Actor: ${payload.actor_id}`);
+                    console.log(`Linkage source: ${payload.linkage_source}`);
+                    console.log("Mode: remote reflects local (replace_missing=true)");
                     console.log(`Local document count: ${String(payload.local_document_count)}`);
-                    console.log(`Imported: ${String(payload.imported ?? "unknown")}`);
-                    console.log(`Created: ${String(payload.created ?? "unknown")}`);
-                    console.log(`Updated: ${String(payload.updated ?? "unknown")}`);
-                    console.log(`Deleted: ${String(payload.deleted ?? "unknown")}`);
+                    console.log(`Imported: ${String(payload.imported)}`);
+                    console.log(`Created: ${String(payload.created)}`);
+                    console.log(`Updated: ${String(payload.updated)}`);
+                    console.log(`Deleted: ${String(payload.deleted)}`);
                     console.log(`Remote document count: ${String(payload.remote_document_count ?? "unknown")}`);
+                    console.log(`Last imported at: ${payload.last_imported_at}`);
                 }
                 return 0;
             }
             if (subcommand === "ls") {
-                const snapshot = await client.getSnapshot(parsed.prefix);
+                let snapshot;
+                try {
+                    snapshot = await client.getSnapshot(parsed.prefix);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Remote ls failed using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                }
                 const paths = (snapshot.documents ?? [])
                     .map((document) => (typeof document.path === "string" ? document.path : ""))
                     .filter(Boolean)
@@ -1019,6 +1076,7 @@ async function main() {
                     endpoint: context.mergedConfig.endpoint,
                     pod_name: context.mergedConfig.pod_name,
                     actor_id: context.mergedConfig.actor_id,
+                    linkage_source: context.linkageSource,
                     prefix: parsed.prefix ?? null,
                     paths,
                 };
@@ -1043,7 +1101,17 @@ async function main() {
                 if (!documentPath.startsWith(".reffy/")) {
                     throw new Error("reffy remote cat requires a canonical path rooted at .reffy/");
                 }
-                const document = await client.getDocument(documentPath);
+                let document;
+                try {
+                    document = await client.getDocument(documentPath);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Remote cat failed using ${describeRemoteLinkage(context.mergedConfig)}: ${message}`);
+                }
+                if (!document.document) {
+                    throw new Error(`Remote document not found using ${describeRemoteLinkage(context.mergedConfig)}: ${documentPath}`);
+                }
                 const payload = {
                     status: "ok",
                     command: "remote",
@@ -1051,13 +1119,14 @@ async function main() {
                     endpoint: context.mergedConfig.endpoint,
                     pod_name: context.mergedConfig.pod_name,
                     actor_id: context.mergedConfig.actor_id,
-                    document: document.document ?? null,
+                    linkage_source: context.linkageSource,
+                    document: document.document,
                 };
                 if (output === "json") {
                     printResult(output, payload);
                 }
                 else {
-                    const content = typeof document.document?.content === "string" ? document.document.content : "";
+                    const content = typeof document.document.content === "string" ? document.document.content : "";
                     process.stdout.write(content);
                     if (!content.endsWith("\n")) {
                         process.stdout.write("\n");

package/dist/gitignore.d.ts

@@ -0,0 +1,4 @@
+export declare function ensureGitignoreEntries(repoRoot: string, entries: string[]): Promise<{
+    path: string;
+    added: string[];
+}>;

package/dist/gitignore.js

@@ -0,0 +1,31 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+function normalizeLines(content) {
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+export async function ensureGitignoreEntries(repoRoot, entries) {
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const current = await fs.readFile(gitignorePath, "utf8").catch(() => "");
+    const existing = new Set(normalizeLines(current));
+    const added = [];
+    for (const entry of entries) {
+        const normalized = entry.trim();
+        if (!normalized || existing.has(normalized))
+            continue;
+        existing.add(normalized);
+        added.push(normalized);
+    }
+    if (added.length === 0) {
+        return { path: gitignorePath, added };
+    }
+    const nextLines = current.length > 0 ? current.replace(/\s*$/, "").split(/\r?\n/) : [];
+    if (nextLines.length > 0 && nextLines[nextLines.length - 1] !== "") {
+        nextLines.push("");
+    }
+    nextLines.push(...added);
+    await fs.writeFile(gitignorePath, `${nextLines.join("\n")}\n`, "utf8");
+    return { path: gitignorePath, added };
+}

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./man
 export { runDoctor } from "./doctor.js";
 export { createPlanScaffold } from "./plan.js";
 export { loadDotEnvIfPresent, parseDotEnv } from "./env.js";
+export { ensureGitignoreEntries } from "./gitignore.js";
 export { collectWorkspaceDocuments, ensureRemoteInit, extractWorkspaceIdentity, mergeRemoteConfig, PaseoRemoteClient, readRemoteConfig, resolveRemoteConfigPath, toCanonicalRemotePath, writeRemoteConfig, } from "./remote.js";
 export { listSpecs, showSpec } from "./spec-runtime.js";

package/dist/index.js

@@ -3,5 +3,6 @@ export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./man
 export { runDoctor } from "./doctor.js";
 export { createPlanScaffold } from "./plan.js";
 export { loadDotEnvIfPresent, parseDotEnv } from "./env.js";
+export { ensureGitignoreEntries } from "./gitignore.js";
 export { collectWorkspaceDocuments, ensureRemoteInit, extractWorkspaceIdentity, mergeRemoteConfig, PaseoRemoteClient, readRemoteConfig, resolveRemoteConfigPath, toCanonicalRemotePath, writeRemoteConfig, } from "./remote.js";
 export { listSpecs, showSpec } from "./spec-runtime.js";

package/dist/remote.d.ts

@@ -17,10 +17,18 @@ export interface EnsureRemoteInitResult {
     created_pod: boolean;
     created_actor: boolean;
 }
+export interface ValidatedImportResult {
+    imported: number;
+    created: number;
+    updated: number;
+    deleted: number;
+}
 export declare function resolveRemoteConfigPath(repoRoot: string): string;
 export declare function readRemoteConfig(repoRoot: string): Promise<RemoteLinkConfig | null>;
 export declare function writeRemoteConfig(repoRoot: string, config: RemoteLinkConfig): Promise<string>;
+export declare function updateRemoteConfigMetadata(repoRoot: string, patch: Partial<Pick<RemoteLinkConfig, "last_imported_at">>): Promise<RemoteLinkConfig | null>;
 export declare function mergeRemoteConfig(stored: RemoteLinkConfig | null, overrides: Partial<Pick<RemoteLinkConfig, "endpoint" | "pod_name" | "actor_id">>): RemoteLinkConfig | null;
+export declare function describeRemoteLinkage(config: Pick<RemoteLinkConfig, "endpoint" | "pod_name" | "actor_id">): string;
 export declare class PaseoRemoteClient {
     private readonly config;
     constructor(config: Pick<RemoteLinkConfig, "endpoint" | "pod_name" | "actor_id">);
@@ -52,5 +60,6 @@ export declare function extractWorkspaceIdentity(summary: RemoteWorkspaceSummary
     document_count?: number | null;
 };
 export declare function assertRemoteIdentity(summary: RemoteWorkspaceSummary, identity: WorkspaceIdentity): void;
+export declare function validateImportResult(result: RemoteImportResult): ValidatedImportResult;
 export declare function toCanonicalRemotePath(refsDir: string, filePath: string): string;
 export declare function collectWorkspaceDocuments(repoRoot: string): Promise<RemoteDocument[]>;

package/dist/remote.js

@@ -62,6 +62,17 @@ export async function writeRemoteConfig(repoRoot, config) {
     await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf8");
     return configPath;
 }
+export async function updateRemoteConfigMetadata(repoRoot, patch) {
+    const existing = await readRemoteConfig(repoRoot);
+    if (!existing)
+        return null;
+    const next = {
+        ...existing,
+        ...patch,
+    };
+    await writeRemoteConfig(repoRoot, next);
+    return next;
+}
 export function mergeRemoteConfig(stored, overrides) {
     if (!stored && !overrides.endpoint && !overrides.pod_name && !overrides.actor_id) {
         return null;
@@ -81,6 +92,9 @@ export function mergeRemoteConfig(stored, overrides) {
         last_imported_at: stored?.last_imported_at,
     };
 }
+export function describeRemoteLinkage(config) {
+    return `endpoint=${config.endpoint} pod=${config.pod_name} actor=${config.actor_id}`;
+}
 async function http(url, init = {}) {
     const headers = new Headers(init.headers ?? {});
     if (!headers.has("Content-Type") && init.body) {
@@ -219,6 +233,19 @@ export function assertRemoteIdentity(summary, identity) {
         throw new Error(`Remote identity mismatch: local=${identity.project_id}/${identity.workspace_name} remote=${String(remote.project_id)}/${String(remote.workspace_name)}`);
     }
 }
+export function validateImportResult(result) {
+    const requiredKeys = ["imported", "created", "updated", "deleted"];
+    const missing = requiredKeys.filter((key) => typeof result[key] !== "number");
+    if (missing.length > 0) {
+        throw new Error(`Remote import response missing numeric field(s): ${missing.join(", ")}`);
+    }
+    return {
+        imported: result.imported,
+        created: result.created,
+        updated: result.updated,
+        deleted: result.deleted,
+    };
+}
 async function collectFiles(dirPath) {
     const entries = await fs.readdir(dirPath, { withFileTypes: true });
     const files = [];

package/package.json

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