reffy-cli 1.4.2 → 1.7.0

package/dist/index.d.ts

@@ -4,5 +4,5 @@ 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 { collectWorkspaceDocuments, ensureManagerInit, ensureWorkspaceTarget, extractWorkspaceSummaryIdentity, PaseoManagerClient, PaseoWorkspaceBackendClient, readRemoteConfig, resolveRemoteConfigPath, resolveRemoteTarget, resolveSelectedWorkspaceId, toCanonicalRemotePath, writeRemoteConfig, } from "./remote.js";
 export { listSpecs, showSpec } from "./spec-runtime.js";

package/dist/index.js

@@ -4,5 +4,5 @@ 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 { collectWorkspaceDocuments, ensureManagerInit, ensureWorkspaceTarget, extractWorkspaceSummaryIdentity, PaseoManagerClient, PaseoWorkspaceBackendClient, readRemoteConfig, resolveRemoteConfigPath, resolveRemoteTarget, resolveSelectedWorkspaceId, toCanonicalRemotePath, writeRemoteConfig, } from "./remote.js";
 export { listSpecs, showSpec } from "./spec-runtime.js";

package/dist/manifest.d.ts

@@ -1,7 +1,11 @@
 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 interface ManifestIdentityDefaults {
+    project_id: string;
+    workspace_ids: string[];
+}
+export declare function deriveManifestIdentity(repoRoot: string): ManifestIdentityDefaults;
 export declare function createManifest(repoRoot: string, now?: string): Manifest;
 export declare function normalizeManifest(raw: unknown, repoRoot: string): Manifest;
 export declare function inferArtifactType(filePath: string): {

package/dist/manifest.js

@@ -13,6 +13,7 @@ const KIND_EXTENSIONS = {
     file: [],
 };
 const PROJECT_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const WORKSPACE_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);
@@ -25,11 +26,22 @@ function isIsoDate(value) {
 function isProjectId(value) {
     return typeof value === "string" && PROJECT_ID_PATTERN.test(value);
 }
+function isWorkspaceId(value) {
+    return typeof value === "string" && WORKSPACE_ID_PATTERN.test(value);
+}
 function isWorkspaceName(value) {
     return (typeof value === "string" &&
         value.trim().length > 0 &&
         !/[\\/\r\n\t]/.test(value));
 }
+function slugifyWorkspaceId(value) {
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug : null;
+}
 function slugifyIdentity(value) {
     return value
         .trim()
@@ -51,18 +63,33 @@ export function deriveManifestIdentity(repoRoot) {
     const identity = candidate || FALLBACK_WORKSPACE_ID;
     return {
         project_id: identity,
-        workspace_name: identity,
+        workspace_ids: [identity],
     };
 }
 export function createManifest(repoRoot, now = new Date().toISOString()) {
+    const defaults = deriveManifestIdentity(repoRoot);
     return {
         version: MANIFEST_VERSION,
         created_at: now,
         updated_at: now,
-        ...deriveManifestIdentity(repoRoot),
+        project_id: defaults.project_id,
+        workspace_ids: defaults.workspace_ids,
         artifacts: [],
     };
 }
+function normalizeWorkspaceIds(raw, fallback) {
+    const explicit = Array.isArray(raw.workspace_ids)
+        ? raw.workspace_ids.filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+        : null;
+    if (explicit && explicit.length > 0) {
+        return Array.from(new Set(explicit.map((entry) => entry.trim())));
+    }
+    if (typeof raw.workspace_name === "string" && raw.workspace_name.trim().length > 0) {
+        const migrated = slugifyWorkspaceId(raw.workspace_name) ?? raw.workspace_name.trim();
+        return [migrated];
+    }
+    return [...fallback];
+}
 export function normalizeManifest(raw, repoRoot) {
     const now = new Date().toISOString();
     const defaults = deriveManifestIdentity(repoRoot);
@@ -71,7 +98,8 @@ export function normalizeManifest(raw, repoRoot) {
             version: 0,
             created_at: now,
             updated_at: now,
-            ...defaults,
+            project_id: defaults.project_id,
+            workspace_ids: defaults.workspace_ids,
             artifacts: raw,
         };
     }
@@ -79,12 +107,13 @@ export function normalizeManifest(raw, repoRoot) {
         return createManifest(repoRoot, now);
     }
     const artifacts = Array.isArray(raw.artifacts) ? raw.artifacts : [];
+    const workspaceIds = normalizeWorkspaceIds(raw, defaults.workspace_ids);
     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,
+        workspace_ids: workspaceIds,
         artifacts,
     };
 }
@@ -183,8 +212,32 @@ export async function validateManifest(manifestPath, artifactsDir) {
     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 (raw.workspace_ids !== undefined) {
+        if (!Array.isArray(raw.workspace_ids) || raw.workspace_ids.length === 0) {
+            errors.push("workspace_ids must be a non-empty array of kebab-case strings when provided");
+        }
+        else {
+            const seen = new Set();
+            raw.workspace_ids.forEach((entry, index) => {
+                if (!isWorkspaceId(entry)) {
+                    errors.push(`workspace_ids[${index}] must be a non-empty kebab-case string`);
+                    return;
+                }
+                if (seen.has(entry)) {
+                    errors.push(`workspace_ids[${index}] duplicates "${entry}"`);
+                    return;
+                }
+                seen.add(entry);
+            });
+        }
+    }
+    if (raw.workspace_name !== undefined) {
+        if (!isWorkspaceName(raw.workspace_name)) {
+            errors.push("workspace_name must be a non-empty string without path separators or control characters");
+        }
+        else if (raw.workspace_ids === undefined) {
+            warnings.push("workspace_name is deprecated; migrate to workspace_ids");
+        }
     }
     if (!Array.isArray(raw.artifacts)) {
         errors.push("artifacts must be an array");

package/dist/remote.d.ts

@@ -1,21 +1,23 @@
-import type { RemoteDocument, RemoteImportResult, RemoteLinkConfig, RemoteWorkspaceSummary } from "./types.js";
-export declare const REMOTE_CONFIG_VERSION = 1;
+import type { RemoteActorIdentity, RemoteDocument, RemoteImportResult, RemoteLinkConfig, RemoteTarget, RemoteWorkspaceSummary } from "./types.js";
+export declare const REMOTE_CONFIG_VERSION = 4;
 export declare const REMOTE_PROVIDER = "paseo";
+export declare const REMOTE_BACKEND_ACTOR_TYPE = "reffyRemoteBackend";
+export declare const REMOTE_BACKEND_VERSION = "v2";
+export declare const REMOTE_MANAGER_ACTOR_TYPE = "reffyWorkspaceManager";
+export declare const REMOTE_MANAGER_VERSION = "v1";
 export interface WorkspaceIdentity {
     project_id: string;
-    workspace_name: string;
+    workspace_id: string;
 }
-export interface EnsureRemoteInitOptions {
-    endpoint: string;
-    podName?: string;
-    actorId?: string;
-    provision: boolean;
-    identity: WorkspaceIdentity;
+export interface ManifestIdentityLike {
+    project_id?: string;
+    workspace_ids?: string[];
 }
-export interface EnsureRemoteInitResult {
-    config: RemoteLinkConfig;
-    created_pod: boolean;
-    created_actor: boolean;
+export interface ResolvedRemoteTarget {
+    endpoint: string;
+    manager: RemoteActorIdentity;
+    workspace_backend: RemoteActorIdentity;
+    last_imported_at?: string;
 }
 export interface ValidatedImportResult {
     imported: number;
@@ -24,42 +26,149 @@ export interface ValidatedImportResult {
     deleted: number;
 }
 export declare function resolveRemoteConfigPath(repoRoot: string): string;
+export declare function resolveSelectedWorkspaceId(identity: ManifestIdentityLike, override: string | undefined): string;
+export declare function requireWorkspaceIdentity(identity: ManifestIdentityLike, selectedWorkspaceId: string): WorkspaceIdentity;
 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">);
+export declare function updateRemoteConfigMetadata(repoRoot: string, workspaceId: string, patch: Partial<Pick<RemoteTarget, "last_imported_at">>): Promise<RemoteLinkConfig | null>;
+export declare function removeWorkspaceTarget(repoRoot: string, existing: RemoteLinkConfig, workspaceId: string): Promise<{
+    config: RemoteLinkConfig;
+    existed: boolean;
+}>;
+export declare function upsertWorkspaceTarget(repoRoot: string, existing: RemoteLinkConfig, workspaceId: string, workspaceBackend: RemoteActorIdentity): Promise<RemoteLinkConfig>;
+export declare function resolveRemoteTarget(stored: RemoteLinkConfig | null, workspaceId: string, endpoint: string): ResolvedRemoteTarget | null;
+export declare function describeRemoteLinkage(linkage: {
+    endpoint: string;
+    manager: RemoteActorIdentity;
+    workspace_backend: RemoteActorIdentity;
+    workspace_id: string;
+}): string;
+export declare class RemoteHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly url: string;
+    readonly method: string;
+    constructor(status: number, statusText: string, body: string, url: string, method: string);
+}
+export interface ManagerWorkspaceResponse {
+    workspace?: {
+        workspace_id?: string;
+        backend?: {
+            pod_name?: string;
+            actor_id?: string;
+        };
+        metadata?: Record<string, unknown>;
+    };
+}
+export interface ManagerProjectListResponse {
+    projects?: Array<{
+        project_id?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+export interface ManagerProjectResponse {
+    project?: {
+        project_id?: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+export interface CreateManagerActorResult {
+    actorId: string;
+    managerAuthToken: string;
+}
+export declare class PaseoManagerClient {
+    private readonly endpoint;
+    private readonly identity;
+    private readonly token?;
+    constructor(endpoint: string, identity: RemoteActorIdentity, token?: string);
+    private base;
+    private requireToken;
     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;
-        }>;
+    createManagerActor(podName: string): Promise<CreateManagerActorResult>;
+    createWorkspace(workspaceId: string, metadata?: Record<string, unknown>): Promise<RemoteActorIdentity>;
+    getWorkspace(workspaceId: string): Promise<RemoteActorIdentity>;
+    registerProject(workspaceId: string, projectId: string): Promise<{
+        alreadyRegistered: boolean;
     }>;
-    getDocument(documentPath: string): Promise<{
-        document?: {
-            path?: string;
-            content?: string;
-            content_type?: string;
-        };
+    listProjects(workspaceId: string): Promise<ManagerProjectListResponse>;
+    getProject(workspaceId: string, projectId: string): Promise<ManagerProjectResponse>;
+    deleteWorkspace(workspaceId: string): Promise<{
+        alreadyAbsent: boolean;
     }>;
 }
-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;
+export interface ProjectDocumentListResponse {
+    documents?: Array<{
+        path?: string;
+        content?: string;
+        content_type?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+export interface ProjectDocumentResponse {
+    document?: {
+        path?: string;
+        content?: string;
+        content_type?: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+export interface ProjectSnapshotResponse {
+    snapshot?: Record<string, unknown>;
+    documents?: Array<{
+        path?: string;
+    }>;
+}
+export declare class PaseoWorkspaceBackendClient {
+    private readonly endpoint;
+    private readonly identity;
+    private readonly token;
+    constructor(endpoint: string, identity: RemoteActorIdentity, token: string);
+    private base;
+    getWorkspace(): Promise<RemoteWorkspaceSummary>;
+    importProject(projectId: string, documents: RemoteDocument[], replaceMissing?: boolean): Promise<RemoteImportResult>;
+    listProjectDocuments(projectId: string, options?: {
+        prefix?: string;
+    }): Promise<ProjectDocumentListResponse>;
+    getProjectDocument(projectId: string, documentPath: string): Promise<ProjectDocumentResponse>;
+    getProjectSnapshot(projectId: string): Promise<ProjectSnapshotResponse>;
+}
+export interface EnsureManagerInitOptions {
+    endpoint: string;
+    managerPodName?: string;
+    managerActorId?: string;
+    provision: boolean;
+    existingConfig: RemoteLinkConfig | null;
+}
+export interface EnsureManagerInitResult {
+    config: RemoteLinkConfig;
+    created_pod: boolean;
+    created_actor: boolean;
+    /** Bearer token returned by the backend when a fresh manager actor was created. Only set when `created_actor` is true. */
+    manager_auth_token?: string;
+}
+export declare function ensureManagerInit(repoRoot: string, options: EnsureManagerInitOptions): Promise<EnsureManagerInitResult>;
+export type WorkspaceTargetMode = "create" | "resolve" | "auto";
+export interface EnsureWorkspaceTargetOptions {
+    workspaceId: string;
+    mode: WorkspaceTargetMode;
+    endpoint: string;
+    token: string;
+    metadata?: Record<string, unknown>;
+}
+export interface EnsureWorkspaceTargetResult {
+    config: RemoteLinkConfig;
+    workspace_backend: RemoteActorIdentity;
+    outcome: "created" | "resolved" | "reused";
+}
+export declare function ensureWorkspaceTarget(repoRoot: string, config: RemoteLinkConfig, options: EnsureWorkspaceTargetOptions): Promise<EnsureWorkspaceTargetResult>;
+export declare function extractWorkspaceSummaryIdentity(summary: RemoteWorkspaceSummary): {
+    workspace_id?: string | null;
+    actor_type?: string | null;
+    backend_version?: string | null;
     document_count?: number | null;
+    registered_project_count?: number | null;
 };
-export declare function assertRemoteIdentity(summary: RemoteWorkspaceSummary, identity: WorkspaceIdentity): void;
+export declare function assertWorkspaceSummaryIdentity(summary: RemoteWorkspaceSummary, expectedWorkspaceId: string): 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[]>;