reffy-cli 1.3.0 → 1.4.0

package/README.md

@@ -33,6 +33,7 @@ Command summary:
 - `reffy plan create`: generates proposal, task, design, and spec scaffolds from indexed Reffy artifacts.
 - `reffy plan validate|list|show|archive`: manages the planning lifecycle under `.reffy/reffyspec/`.
 - `reffy spec list|show`: inspects current spec state under `.reffy/reffyspec/`.
+- `reffy remote init|status|push|ls|cat`: links, publishes, and inspects a Paseo-backed remote `.reffy/` workspace.
 - `reffy diagram render`: renders Mermaid diagrams as SVG or ASCII, including spec-aware generation from compatible `spec.md` files.
 
 Output modes:
@@ -54,11 +55,103 @@ reffy plan create --change-id add-login-flow --artifacts login-idea.md
 reffy plan list --output json
 reffy plan archive add-login-flow
 reffy spec show auth --output json
+reffy remote init --endpoint https://your-paseo-endpoint.example --provision
+reffy remote status --output json
+reffy remote push
+reffy remote ls
+reffy remote cat .reffy/manifest.json
 reffy diagram render --stdin --format svg < diagram.mmd
 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
 ```
 
+## Remote Backend Helper
+
+Reffy includes a Paseo helper bridge at `scripts/reffy-remote-backend-demo.mjs`.
+
+The helper:
+
+- loads `.env` automatically when present
+- reads `project_id` and `workspace_name` from `.reffy/manifest.json`
+- provisions or links a Paseo `reffyRemoteBackend` actor
+- imports the local `.reffy/` workspace
+
+Expected environment variables:
+
+- `PASEO_ENDPOINT` - required unless already exported in the shell
+- `PASEO_POD_NAME` - optional existing pod override
+- `PASEO_ACTOR_ID` - optional existing actor override
+
+Examples:
+
+```bash
+npm run remote:backend:demo
+reffy remote init --provision
+reffy remote push
+```
+
+## Remote Sync
+
+Reffy can publish the local `.reffy/` workspace to a Paseo-backed remote actor and inspect it later with native CLI commands.
+
+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.
+
+### Minimal connection requirement
+
+For the fresh-provision path, the only required connection value is:
+
+- `PASEO_ENDPOINT`
+
+Example `.env`:
+
+```bash
+PASEO_ENDPOINT="https://your-paseo-endpoint.example"
+```
+
+That is enough for:
+
+```bash
+reffy remote init --provision
+```
+
+Optional overrides:
+
+- `PASEO_POD_NAME` if you want to reuse an existing Paseo pod
+- `PASEO_ACTOR_ID` if you want to reuse an existing backend actor
+
+Reffy does not require separate `REFFY_PROJECT_ID` or `REFFY_WORKSPACE_NAME` values for the normal case because those come from `.reffy/manifest.json`.
+
+### Saved remote linkage
+
+After `reffy remote init`, Reffy stores the local pointer to the linked backend actor in:
+
+- `.reffy/state/remote.json`
+
+That file contains the connection tuple Reffy uses to reach the backend:
+
+- `endpoint`
+- `pod_name`
+- `actor_id`
+
+This file is local runtime state. It is not part of the synced remote workspace and is intentionally excluded from `reffy remote push`.
+
+### Example flow
+
+```bash
+reffy init
+reffy remote init --provision
+reffy remote status
+reffy remote push
+reffy remote ls
+reffy remote cat .reffy/manifest.json
+```
+
 ## Manifest Contract
 
 Reffy keeps workspace metadata in `.reffy/manifest.json`. New managed manifests include both core timestamps and workspace identity:

package/dist/cli.js

@@ -4,10 +4,12 @@ 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 { loadDotEnvIfPresent } from "./env.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 { DEFAULT_REFS_DIRNAME, detectWorkspaceState, looksLikeRefsDir } from "./refs-paths.js";
 import { prepareCanonicalPlanningLayout } from "./planning-workspace.js";
 import { ReferencesStore } from "./storage.js";
@@ -431,6 +433,7 @@ function usage() {
         "  summarize  Generate a read-only summary of indexed Reffy artifacts.",
         "  plan       Generate and manage ReffySpec planning scaffolds from indexed Reffy artifacts.",
         "  spec       Inspect current specs from the ReffySpec layout.",
+        "  remote     Link, publish, and inspect a Paseo-backed remote Reffy workspace.",
         "  diagram    Render Mermaid diagrams (supports SVG and ASCII).",
     ].join("\n");
 }
@@ -478,6 +481,24 @@ function planUsage() {
         "  --force            Overwrite an existing non-empty change directory",
     ].join("\n");
 }
+function remoteUsage() {
+    return [
+        "Usage:",
+        "  reffy remote init [--repo PATH] [--output text|json] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--provision] [--env-file PATH]",
+        "  reffy remote status [--repo PATH] [--output text|json] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
+        "  reffy remote push [--repo PATH] [--output text|json] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
+        "  reffy remote ls [--repo PATH] [--output text|json] [--prefix PATH] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
+        "  reffy remote cat <path> [--repo PATH] [--output text|json] [--endpoint URL] [--pod-name NAME] [--actor-id ID] [--env-file PATH]",
+        "",
+        "Options:",
+        "  --endpoint URL    Paseo base URL. Defaults to saved config or PASEO_ENDPOINT/.env.",
+        "  --pod-name NAME   Paseo pod name. Defaults to saved config or PASEO_POD_NAME/.env.",
+        "  --actor-id ID     Paseo actor id. Defaults to saved config or PASEO_ACTOR_ID/.env.",
+        "  --provision       Create missing pod/actor during `remote init`.",
+        "  --prefix PATH     Prefix filter for `remote ls`.",
+        "  --env-file PATH   Dotenv file to load before resolving env-backed options. Defaults to .env.",
+    ].join("\n");
+}
 function parseDiagramArgs(argv) {
     const repoRoot = parseRepoArg(argv);
     const args = {
@@ -654,6 +675,129 @@ function parsePlanArgs(argv) {
     }
     return args;
 }
+function parseRemoteArgs(argv) {
+    const repoRoot = parseRepoArg(argv);
+    const args = {
+        repoRoot,
+        provision: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--repo") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--repo="))
+            continue;
+        if (arg === "--json")
+            continue;
+        if (arg === "--output") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--output="))
+            continue;
+        if (arg === "--endpoint") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--endpoint requires a value");
+            args.endpoint = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--endpoint=")) {
+            args.endpoint = arg.split("=", 2)[1];
+            continue;
+        }
+        if (arg === "--pod-name") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--pod-name requires a value");
+            args.podName = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--pod-name=")) {
+            args.podName = arg.split("=", 2)[1];
+            continue;
+        }
+        if (arg === "--actor-id") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--actor-id requires a value");
+            args.actorId = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--actor-id=")) {
+            args.actorId = arg.split("=", 2)[1];
+            continue;
+        }
+        if (arg === "--env-file") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--env-file requires a value");
+            args.envFile = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--env-file=")) {
+            args.envFile = arg.split("=", 2)[1];
+            continue;
+        }
+        if (arg === "--prefix") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--prefix requires a value");
+            args.prefix = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--prefix=")) {
+            args.prefix = arg.split("=", 2)[1];
+            continue;
+        }
+        if (arg === "--provision") {
+            args.provision = true;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            throw new Error(`Unknown remote option: ${arg}`);
+        }
+    }
+    return args;
+}
+function getRemotePositionalArgs(argv) {
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--repo" ||
+            arg === "--output" ||
+            arg === "--endpoint" ||
+            arg === "--pod-name" ||
+            arg === "--actor-id" ||
+            arg === "--env-file" ||
+            arg === "--prefix") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--repo=") ||
+            arg.startsWith("--output=") ||
+            arg.startsWith("--endpoint=") ||
+            arg.startsWith("--pod-name=") ||
+            arg.startsWith("--actor-id=") ||
+            arg.startsWith("--env-file=") ||
+            arg.startsWith("--prefix=") ||
+            arg === "--json" ||
+            arg === "--provision") {
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        positionals.push(arg);
+    }
+    return positionals;
+}
 function printSection(title, values) {
     console.log(`${title}:`);
     if (values.length === 0) {
@@ -664,6 +808,24 @@ function printSection(title, values) {
         console.log(`- ${value}`);
     }
 }
+async function resolveRemoteContext(args) {
+    await loadDotEnvIfPresent(args.repoRoot, args.envFile ?? ".env");
+    const store = new ReferencesStore(args.repoRoot);
+    const identity = requireWorkspaceIdentity(await store.getWorkspaceIdentity());
+    const savedConfig = await readRemoteConfig(args.repoRoot);
+    const mergedConfig = mergeRemoteConfig(savedConfig, {
+        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,
+    });
+    return {
+        store,
+        identity,
+        configPath: resolveRemoteConfigPath(args.repoRoot),
+        savedConfig,
+        mergedConfig,
+    };
+}
 async function main() {
     const [, , command, ...rest] = process.argv;
     if (!command || command === "--help" || command === "-h") {
@@ -713,6 +875,216 @@ async function main() {
         }
         return 0;
     }
+    if (command === "remote") {
+        const [subcommand, ...remoteArgs] = rest;
+        if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+            console.error(remoteUsage());
+            return 1;
+        }
+        const output = parseOutputMode(remoteArgs);
+        const parsed = parseRemoteArgs(remoteArgs);
+        try {
+            if (subcommand === "init") {
+                const { identity } = 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)");
+                }
+                const result = await ensureRemoteInit(parsed.repoRoot, {
+                    endpoint,
+                    podName: parsed.podName ?? process.env.PASEO_POD_NAME,
+                    actorId: parsed.actorId ?? process.env.PASEO_ACTOR_ID,
+                    provision: parsed.provision,
+                    identity,
+                });
+                const payload = {
+                    status: "ok",
+                    command: "remote",
+                    subcommand: "init",
+                    provider: result.config.provider,
+                    config_path: resolveRemoteConfigPath(parsed.repoRoot),
+                    endpoint: result.config.endpoint,
+                    pod_name: result.config.pod_name,
+                    actor_id: result.config.actor_id,
+                    created_pod: result.created_pod,
+                    created_actor: result.created_actor,
+                    project_id: identity.project_id,
+                    workspace_name: identity.workspace_name,
+                };
+                if (output === "json") {
+                    printResult(output, payload);
+                }
+                else {
+                    console.log("Remote linkage ready");
+                    console.log(`Config: ${payload.config_path}`);
+                    console.log(`Endpoint: ${payload.endpoint}`);
+                    console.log(`Pod: ${payload.pod_name}`);
+                    console.log(`Actor: ${payload.actor_id}`);
+                    console.log(`Project identity: ${payload.project_id}`);
+                    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"}`);
+                }
+                return 0;
+            }
+            const context = await resolveRemoteContext(parsed);
+            if (!context.mergedConfig) {
+                throw new Error(`Remote linkage is not configured. Run \`reffy remote init\` or provide endpoint, pod name, and actor id. Expected config path: ${context.configPath}`);
+            }
+            const client = new PaseoRemoteClient(context.mergedConfig);
+            if (subcommand === "status") {
+                const workspace = await client.getWorkspace();
+                assertRemoteIdentity(workspace, context.identity);
+                const remoteIdentity = extractWorkspaceIdentity(workspace);
+                const payload = {
+                    status: "ok",
+                    command: "remote",
+                    subcommand: "status",
+                    config_path: context.configPath,
+                    provider: context.mergedConfig.provider,
+                    endpoint: context.mergedConfig.endpoint,
+                    pod_name: context.mergedConfig.pod_name,
+                    actor_id: context.mergedConfig.actor_id,
+                    local_identity: context.identity,
+                    remote_identity: {
+                        project_id: remoteIdentity.project_id,
+                        workspace_name: remoteIdentity.workspace_name,
+                    },
+                    document_count: remoteIdentity.document_count,
+                    workspace,
+                };
+                if (output === "json") {
+                    printResult(output, payload);
+                }
+                else {
+                    console.log("Remote workspace reachable");
+                    console.log(`Config: ${payload.config_path}`);
+                    console.log(`Endpoint: ${payload.endpoint}`);
+                    console.log(`Pod: ${payload.pod_name}`);
+                    console.log(`Actor: ${payload.actor_id}`);
+                    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")}`);
+                }
+                return 0;
+            }
+            if (subcommand === "push") {
+                const documents = await collectWorkspaceDocuments(parsed.repoRoot);
+                const importResult = await client.importWorkspace(documents, true);
+                const workspace = await client.getWorkspace();
+                assertRemoteIdentity(workspace, context.identity);
+                const payload = {
+                    status: "ok",
+                    command: "remote",
+                    subcommand: "push",
+                    endpoint: context.mergedConfig.endpoint,
+                    pod_name: context.mergedConfig.pod_name,
+                    actor_id: context.mergedConfig.actor_id,
+                    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,
+                    remote_document_count: extractWorkspaceIdentity(workspace).document_count,
+                };
+                if (output === "json") {
+                    printResult(output, payload);
+                }
+                else {
+                    console.log("Remote push complete");
+                    console.log(`Endpoint: ${payload.endpoint}`);
+                    console.log(`Pod: ${payload.pod_name}`);
+                    console.log(`Actor: ${payload.actor_id}`);
+                    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(`Remote document count: ${String(payload.remote_document_count ?? "unknown")}`);
+                }
+                return 0;
+            }
+            if (subcommand === "ls") {
+                const snapshot = await client.getSnapshot(parsed.prefix);
+                const paths = (snapshot.documents ?? [])
+                    .map((document) => (typeof document.path === "string" ? document.path : ""))
+                    .filter(Boolean)
+                    .sort();
+                const payload = {
+                    status: "ok",
+                    command: "remote",
+                    subcommand: "ls",
+                    endpoint: context.mergedConfig.endpoint,
+                    pod_name: context.mergedConfig.pod_name,
+                    actor_id: context.mergedConfig.actor_id,
+                    prefix: parsed.prefix ?? null,
+                    paths,
+                };
+                if (output === "json") {
+                    printResult(output, payload);
+                }
+                else if (paths.length === 0) {
+                    console.log("(none)");
+                }
+                else {
+                    for (const entry of paths) {
+                        console.log(entry);
+                    }
+                }
+                return 0;
+            }
+            if (subcommand === "cat") {
+                const [documentPath] = getRemotePositionalArgs(remoteArgs);
+                if (!documentPath) {
+                    throw new Error("reffy remote cat requires a document path");
+                }
+                if (!documentPath.startsWith(".reffy/")) {
+                    throw new Error("reffy remote cat requires a canonical path rooted at .reffy/");
+                }
+                const document = await client.getDocument(documentPath);
+                const payload = {
+                    status: "ok",
+                    command: "remote",
+                    subcommand: "cat",
+                    endpoint: context.mergedConfig.endpoint,
+                    pod_name: context.mergedConfig.pod_name,
+                    actor_id: context.mergedConfig.actor_id,
+                    document: document.document ?? null,
+                };
+                if (output === "json") {
+                    printResult(output, payload);
+                }
+                else {
+                    const content = typeof document.document?.content === "string" ? document.document.content : "";
+                    process.stdout.write(content);
+                    if (!content.endsWith("\n")) {
+                        process.stdout.write("\n");
+                    }
+                }
+                return 0;
+            }
+            console.error(`Unknown remote subcommand: ${subcommand}`);
+            console.error(remoteUsage());
+            return 1;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (output === "json") {
+                printResult(output, {
+                    status: "error",
+                    command: "remote",
+                    subcommand,
+                    error: message,
+                });
+            }
+            else {
+                console.error(message);
+            }
+            return 1;
+        }
+    }
     if (command === "plan") {
         const [subcommand, ...planArgs] = rest;
         if (!subcommand || subcommand === "--help" || subcommand === "-h") {

package/dist/env.d.ts

@@ -0,0 +1,5 @@
+export declare function parseDotEnv(content: string): Record<string, string>;
+export declare function loadDotEnvIfPresent(repoRoot: string, envFile?: string): Promise<{
+    loaded: boolean;
+    path: string;
+}>;

package/dist/env.js

@@ -0,0 +1,43 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+function stripQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+export function parseDotEnv(content) {
+    const parsed = {};
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const normalized = trimmed.startsWith("export ")
+            ? trimmed.slice("export ".length).trim()
+            : trimmed;
+        const equalsIndex = normalized.indexOf("=");
+        if (equalsIndex <= 0)
+            continue;
+        const key = normalized.slice(0, equalsIndex).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        const rawValue = normalized.slice(equalsIndex + 1).trim();
+        parsed[key] = stripQuotes(rawValue);
+    }
+    return parsed;
+}
+export async function loadDotEnvIfPresent(repoRoot, envFile = ".env") {
+    const envPath = path.isAbsolute(envFile) ? envFile : path.join(repoRoot, envFile);
+    const text = await fs.readFile(envPath, "utf8").catch(() => null);
+    if (text === null) {
+        return { loaded: false, path: envPath };
+    }
+    const parsed = parseDotEnv(text);
+    for (const [key, value] of Object.entries(parsed)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+    return { loaded: true, path: envPath };
+}

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export { ReferencesStore } from "./storage.js";
 export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./manifest.js";
 export { runDoctor } from "./doctor.js";
 export { createPlanScaffold } from "./plan.js";
+export { loadDotEnvIfPresent, parseDotEnv } from "./env.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

@@ -2,4 +2,6 @@ export { ReferencesStore } from "./storage.js";
 export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./manifest.js";
 export { runDoctor } from "./doctor.js";
 export { createPlanScaffold } from "./plan.js";
+export { loadDotEnvIfPresent, parseDotEnv } from "./env.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

@@ -0,0 +1,56 @@
+import type { RemoteDocument, RemoteImportResult, RemoteLinkConfig, RemoteWorkspaceSummary } from "./types.js";
+export declare const REMOTE_CONFIG_VERSION = 1;
+export declare const REMOTE_PROVIDER = "paseo";
+export interface WorkspaceIdentity {
+    project_id: string;
+    workspace_name: string;
+}
+export interface EnsureRemoteInitOptions {
+    endpoint: string;
+    podName?: string;
+    actorId?: string;
+    provision: boolean;
+    identity: WorkspaceIdentity;
+}
+export interface EnsureRemoteInitResult {
+    config: RemoteLinkConfig;
+    created_pod: boolean;
+    created_actor: boolean;
+}
+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 mergeRemoteConfig(stored: RemoteLinkConfig | null, overrides: Partial<Pick<RemoteLinkConfig, "endpoint" | "pod_name" | "actor_id">>): RemoteLinkConfig | null;
+export declare class PaseoRemoteClient {
+    private readonly config;
+    constructor(config: Pick<RemoteLinkConfig, "endpoint" | "pod_name" | "actor_id">);
+    createPod(): Promise<string>;
+    createActor(identity: WorkspaceIdentity): Promise<string>;
+    getWorkspace(): Promise<RemoteWorkspaceSummary>;
+    importWorkspace(documents: RemoteDocument[], replaceMissing?: boolean): Promise<RemoteImportResult>;
+    getSnapshot(prefix?: string): Promise<{
+        documents?: Array<{
+            path?: string;
+        }>;
+    }>;
+    getDocument(documentPath: string): Promise<{
+        document?: {
+            path?: string;
+            content?: string;
+            content_type?: string;
+        };
+    }>;
+}
+export declare function ensureRemoteInit(repoRoot: string, options: EnsureRemoteInitOptions): Promise<EnsureRemoteInitResult>;
+export declare function requireWorkspaceIdentity(identity: {
+    project_id?: string;
+    workspace_name?: string;
+}): WorkspaceIdentity;
+export declare function extractWorkspaceIdentity(summary: RemoteWorkspaceSummary): {
+    project_id?: string | null;
+    workspace_name?: string | null;
+    document_count?: number | null;
+};
+export declare function assertRemoteIdentity(summary: RemoteWorkspaceSummary, identity: WorkspaceIdentity): void;
+export declare function toCanonicalRemotePath(refsDir: string, filePath: string): string;
+export declare function collectWorkspaceDocuments(repoRoot: string): Promise<RemoteDocument[]>;

package/dist/remote.js

@@ -0,0 +1,275 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveRefsDir } from "./refs-paths.js";
+export const REMOTE_CONFIG_VERSION = 1;
+export const REMOTE_PROVIDER = "paseo";
+const REMOTE_STATE_DIR = path.join("state");
+const REMOTE_CONFIG_FILE = "remote.json";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function normalizeSeparators(value) {
+    return value.split(path.sep).join("/");
+}
+export function resolveRemoteConfigPath(repoRoot) {
+    return path.join(resolveRefsDir(repoRoot), REMOTE_STATE_DIR, REMOTE_CONFIG_FILE);
+}
+export async function readRemoteConfig(repoRoot) {
+    const configPath = resolveRemoteConfigPath(repoRoot);
+    const raw = await fs.readFile(configPath, "utf8").catch(() => null);
+    if (raw === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse remote config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isObject(parsed)) {
+        throw new Error(`Remote config at ${configPath} must be an object`);
+    }
+    if (parsed.version !== REMOTE_CONFIG_VERSION) {
+        throw new Error(`Remote config at ${configPath} must use version ${String(REMOTE_CONFIG_VERSION)}`);
+    }
+    if (parsed.provider !== REMOTE_PROVIDER) {
+        throw new Error(`Remote config at ${configPath} must use provider "${REMOTE_PROVIDER}"`);
+    }
+    if (!isNonEmptyString(parsed.endpoint)) {
+        throw new Error(`Remote config at ${configPath} must define endpoint`);
+    }
+    if (!isNonEmptyString(parsed.pod_name)) {
+        throw new Error(`Remote config at ${configPath} must define pod_name`);
+    }
+    if (!isNonEmptyString(parsed.actor_id)) {
+        throw new Error(`Remote config at ${configPath} must define actor_id`);
+    }
+    return {
+        version: REMOTE_CONFIG_VERSION,
+        provider: REMOTE_PROVIDER,
+        endpoint: parsed.endpoint.trim(),
+        pod_name: parsed.pod_name.trim(),
+        actor_id: parsed.actor_id.trim(),
+        last_imported_at: isNonEmptyString(parsed.last_imported_at) ? parsed.last_imported_at.trim() : undefined,
+    };
+}
+export async function writeRemoteConfig(repoRoot, config) {
+    const configPath = resolveRemoteConfigPath(repoRoot);
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf8");
+    return configPath;
+}
+export function mergeRemoteConfig(stored, overrides) {
+    if (!stored && !overrides.endpoint && !overrides.pod_name && !overrides.actor_id) {
+        return null;
+    }
+    const endpoint = overrides.endpoint ?? stored?.endpoint;
+    const pod_name = overrides.pod_name ?? stored?.pod_name;
+    const actor_id = overrides.actor_id ?? stored?.actor_id;
+    if (!endpoint || !pod_name || !actor_id) {
+        return null;
+    }
+    return {
+        version: REMOTE_CONFIG_VERSION,
+        provider: REMOTE_PROVIDER,
+        endpoint,
+        pod_name,
+        actor_id,
+        last_imported_at: stored?.last_imported_at,
+    };
+}
+async function http(url, init = {}) {
+    const headers = new Headers(init.headers ?? {});
+    if (!headers.has("Content-Type") && init.body) {
+        headers.set("Content-Type", "application/json");
+    }
+    const response = await fetch(url, { ...init, headers });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`${response.status} ${response.statusText} - ${text}`);
+    }
+    return response;
+}
+async function httpJson(url, init = {}) {
+    const response = await http(url, init);
+    return (await response.json());
+}
+function actorBase(config) {
+    return `${config.endpoint}/pods/${config.pod_name}/actors/${config.actor_id}`;
+}
+export class PaseoRemoteClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async createPod() {
+        const result = await httpJson(`${this.config.endpoint}/pods`, { method: "POST" });
+        if (!isNonEmptyString(result.podName)) {
+            throw new Error("Paseo create pod response missing podName");
+        }
+        return result.podName.trim();
+    }
+    async createActor(identity) {
+        const result = await httpJson(`${this.config.endpoint}/pods/${this.config.pod_name}/actors`, {
+            method: "POST",
+            body: JSON.stringify({
+                config: {
+                    actorType: "reffyRemoteBackend",
+                    version: "v1",
+                    schema: { type: "object" },
+                    params: {
+                        project_id: identity.project_id,
+                        workspace_name: identity.workspace_name,
+                        default_lock_ttl_seconds: 120,
+                        max_snapshot_documents: 1000,
+                    },
+                },
+            }),
+        });
+        if (!isNonEmptyString(result.actorId)) {
+            throw new Error("Paseo create actor response missing actorId");
+        }
+        return result.actorId.trim();
+    }
+    async getWorkspace() {
+        return await httpJson(`${actorBase(this.config)}/workspace`);
+    }
+    async importWorkspace(documents, replaceMissing = true) {
+        return await httpJson(`${actorBase(this.config)}/workspace/import`, {
+            method: "POST",
+            body: JSON.stringify({
+                documents,
+                replace_missing: replaceMissing,
+            }),
+        });
+    }
+    async getSnapshot(prefix) {
+        const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
+        return await httpJson(`${actorBase(this.config)}/workspace/snapshot${query}`);
+    }
+    async getDocument(documentPath) {
+        return await httpJson(`${actorBase(this.config)}/workspace/documents?path=${encodeURIComponent(documentPath)}`);
+    }
+}
+export async function ensureRemoteInit(repoRoot, options) {
+    let created_pod = false;
+    let created_actor = false;
+    let podName = options.podName?.trim() || "";
+    let actorId = options.actorId?.trim() || "";
+    if (!options.endpoint.trim()) {
+        throw new Error("Remote init requires an endpoint");
+    }
+    if (!podName && !options.provision) {
+        throw new Error("Remote init requires --pod-name unless --provision is set");
+    }
+    const baseClient = new PaseoRemoteClient({
+        endpoint: options.endpoint.trim(),
+        pod_name: podName || "pending-pod",
+        actor_id: actorId || "pending-actor",
+    });
+    if (!podName) {
+        podName = await baseClient.createPod();
+        created_pod = true;
+    }
+    if (!actorId) {
+        if (!options.provision) {
+            throw new Error("Remote init requires --actor-id unless --provision is set");
+        }
+        const client = new PaseoRemoteClient({
+            endpoint: options.endpoint.trim(),
+            pod_name: podName,
+            actor_id: "pending-actor",
+        });
+        actorId = await client.createActor(options.identity);
+        created_actor = true;
+    }
+    const config = {
+        version: REMOTE_CONFIG_VERSION,
+        provider: REMOTE_PROVIDER,
+        endpoint: options.endpoint.trim(),
+        pod_name: podName,
+        actor_id: actorId,
+    };
+    await writeRemoteConfig(repoRoot, config);
+    return { config, created_pod, created_actor };
+}
+export function requireWorkspaceIdentity(identity) {
+    const project_id = identity.project_id?.trim();
+    const workspace_name = identity.workspace_name?.trim();
+    if (!project_id || !workspace_name) {
+        throw new Error("Remote sync requires .reffy/manifest.json to define project_id and workspace_name");
+    }
+    return { project_id, workspace_name };
+}
+export function extractWorkspaceIdentity(summary) {
+    const workspace = isObject(summary.workspace) ? summary.workspace : {};
+    const stats = isObject(summary.stats) ? summary.stats : {};
+    return {
+        project_id: typeof workspace.project_id === "string" ? workspace.project_id : null,
+        workspace_name: typeof workspace.workspace_name === "string" ? workspace.workspace_name : null,
+        document_count: typeof stats.document_count === "number" ? stats.document_count : null,
+    };
+}
+export function assertRemoteIdentity(summary, identity) {
+    const remote = extractWorkspaceIdentity(summary);
+    if (remote.project_id !== identity.project_id || remote.workspace_name !== identity.workspace_name) {
+        throw new Error(`Remote identity mismatch: local=${identity.project_id}/${identity.workspace_name} remote=${String(remote.project_id)}/${String(remote.workspace_name)}`);
+    }
+}
+async function collectFiles(dirPath) {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "state")
+                continue;
+            files.push(...(await collectFiles(fullPath)));
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function inferContentType(filePath) {
+    if (filePath.endsWith(".json"))
+        return "application/json";
+    if (filePath.endsWith(".md"))
+        return "text/markdown";
+    return "text/plain";
+}
+export function toCanonicalRemotePath(refsDir, filePath) {
+    const relative = normalizeSeparators(path.relative(refsDir, filePath));
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`Cannot convert ${filePath} into a canonical .reffy path`);
+    }
+    return `.reffy/${relative}`;
+}
+export async function collectWorkspaceDocuments(repoRoot) {
+    const refsDir = resolveRefsDir(repoRoot);
+    const stat = await fs.stat(refsDir).catch(() => null);
+    if (!stat || !stat.isDirectory()) {
+        throw new Error(`Reffy directory not found: ${refsDir}`);
+    }
+    const files = await collectFiles(refsDir);
+    const documents = [];
+    for (const fullPath of files.sort()) {
+        const content = await fs.readFile(fullPath, "utf8");
+        const remotePath = toCanonicalRemotePath(refsDir, fullPath);
+        documents.push({
+            path: remotePath,
+            content,
+            content_type: inferContentType(remotePath),
+            metadata: {
+                source: "local-reffy-import",
+                size_bytes: Buffer.byteLength(content, "utf8"),
+            },
+        });
+    }
+    return documents;
+}

package/dist/types.d.ts

@@ -20,3 +20,27 @@ export interface Manifest {
     workspace_name?: string;
     artifacts: Artifact[];
 }
+export interface RemoteLinkConfig {
+    version: number;
+    provider: "paseo";
+    endpoint: string;
+    pod_name: string;
+    actor_id: string;
+    last_imported_at?: string;
+}
+export interface RemoteDocument {
+    path: string;
+    content: string;
+    content_type: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RemoteImportResult {
+    imported?: number;
+    created?: number;
+    updated?: number;
+    deleted?: number;
+}
+export interface RemoteWorkspaceSummary {
+    workspace?: Record<string, unknown>;
+    stats?: Record<string, unknown>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Planning system for AI assisted development.",
   "keywords": [
     "reffy",
@@ -35,6 +35,7 @@
     "prepare": "npm run build",
     "dev": "tsx watch src/cli.ts",
     "check": "tsc --noEmit",
+    "remote:backend:demo": "node scripts/reffy-remote-backend-demo.mjs",
     "test": "npm run build && vitest run --coverage",
     "test:watch": "vitest"
   },