@cleocode/core 2026.9.23 → 2026.9.25

package/dist/cloud/nexus-link.js

@@ -0,0 +1,226 @@
+/**
+ * `cleo project link`: register the current project with Cleo Nexus and bind
+ * the remote project to the local one.
+ *
+ * ## What is sent
+ *
+ * `POST /v1/projects` with `{ projectId, label }` only:
+ *
+ * - `projectId` is the tracked, immutable `.cleo/project-id`
+ *   (`readDeclaredProjectIdentity`), the key the server stores projects under,
+ *   so the remote id IS the local id.
+ * - `label` is the project's display name in plaintext
+ *   ({@link getProjectDisplayName}), or `--label`. It must not look like a path.
+ *
+ * No filesystem path, git remote or directory layout is ever sent.
+ *
+ * ## Idempotency
+ *
+ * Registering the same id again answers 200 (201 on first registration) and
+ * sets the server label to the one sent, so re-linking after a rename updates
+ * the label. Linking twice is safe.
+ *
+ * ## Where the binding lives
+ *
+ * `<project>/.cleo/nexus-link.json`, keyed by API origin. It is machine-local:
+ * `.cleo/.gitignore` denies everything not allow-listed, so the binding (which
+ * names an account's organization) is never committed. It is not
+ * `project-context.json`, which is tracked in git and regenerated by
+ * `cleo upgrade`, and not the project `cleo.db`, so linking never opens or
+ * migrates the task store. Each clone links itself, the same way each machine
+ * signs itself in.
+ *
+ * @task T12712
+ * @epic T12322
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { join, resolve } from 'node:path';
+import { readDeclaredProjectIdentity } from '@cleocode/paths';
+import { z } from 'zod';
+import { getCleoDirAbsolute, resolveOrCwd } from '../paths.js';
+import { getProjectDisplayName } from '../project-info.js';
+import { withLock } from '../store/file-utils.js';
+import { Http, NexusError } from './http.js';
+import { NexusAccountError, requireNexusSession, resolveNexusApiUrl, } from './nexus-auth.js';
+import { FileNexusTokenStore } from './nexus-credentials.js';
+import { registerProject } from './projects.js';
+/** File name of the binding, inside the project's `.cleo/` directory. */
+export const NEXUS_LINK_FILE = 'nexus-link.json';
+/** Longest label the server accepts (`RegisterProjectRequest.label`). */
+export const NEXUS_LABEL_MAX = 120;
+const linkSchema = z.object({
+    apiUrl: z.string(),
+    localProjectId: z.string(),
+    remoteProjectId: z.string(),
+    organizationId: z.string(),
+    label: z.string().nullable(),
+    streamId: z.string(),
+    linkedAt: z.string(),
+});
+const linkFileSchema = z.object({
+    version: z.literal(1),
+    links: z.record(z.string(), linkSchema),
+});
+/**
+ * Path separators and their look-alikes: `/`, `\`, fullwidth ／ ＼, division
+ * slash ∕, set minus ∖, fraction slash ⁄, big solidi ⧸ ⧹, small reverse
+ * solidus ﹨. Plus C0/C1 control characters.
+ */
+const LABEL_FORBIDDEN = /[/\\\uFF0F\uFF3C\u2215\u2216\u2044\u29F8\u29F9\uFE68\u0000-\u001f\u007f-\u009f]/;
+/** The OS account name, or `null` when the platform cannot say. */
+function osUsername() {
+    try {
+        return userInfo().username || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate a project label: 1-120 characters; no path separator or look-alike
+ * slash, no drive letter (`C:`), no leading `~`, no control characters; and
+ * not the OS username, which would leak the account name. A label is a name,
+ * never a path.
+ *
+ * @param raw - Candidate label.
+ * @returns The trimmed label.
+ * @throws {NexusAccountError} `E_NEXUS_INVALID_LABEL`.
+ */
+export function validateNexusProjectLabel(raw) {
+    const label = raw.trim();
+    const pathLike = LABEL_FORBIDDEN.test(label) || label.startsWith('~') || /^[A-Za-z]:/.test(label);
+    if (!label || label.length > NEXUS_LABEL_MAX || pathLike) {
+        throw new NexusAccountError('E_NEXUS_INVALID_LABEL', `invalid project label "${label}": use 1-${NEXUS_LABEL_MAX} characters with no slash or backslash (or look-alike), drive letter or leading "~" (a name, not a path)`, 'pass `--label <name>`');
+    }
+    const username = osUsername();
+    if (username !== null && label.toLowerCase() === username.toLowerCase()) {
+        throw new NexusAccountError('E_NEXUS_INVALID_LABEL', 'the project label equals your OS username, which would reveal it to the server', 'pass `--label <name>` with a different name');
+    }
+    return label;
+}
+/**
+ * The label to send: `--label`, else the project's display name. A project
+ * rooted at the home directory has no meaningful name (its basename is the
+ * account name), so it must be labelled explicitly.
+ */
+function resolveLinkLabel(projectRoot, explicit) {
+    if (explicit !== undefined)
+        return validateNexusProjectLabel(explicit);
+    if (resolve(projectRoot) === resolve(homedir())) {
+        throw new NexusAccountError('E_NEXUS_INVALID_LABEL', 'this project is your home directory; its name would reveal your account name', 'pass `--label <name>`');
+    }
+    return validateNexusProjectLabel(getProjectDisplayName(projectRoot));
+}
+/**
+ * Path of the binding file for a project.
+ *
+ * @param projectRoot - Project root.
+ * @returns `<project>/.cleo/nexus-link.json`.
+ */
+export function nexusLinkPath(projectRoot) {
+    return join(getCleoDirAbsolute(projectRoot), NEXUS_LINK_FILE);
+}
+/** Read the binding file; missing or malformed reads as empty. */
+function readLinkFile(path) {
+    try {
+        const parsed = linkFileSchema.safeParse(JSON.parse(readFileSync(path, 'utf-8')));
+        if (parsed.success)
+            return parsed.data;
+    }
+    catch {
+        /* missing or unreadable */
+    }
+    return { version: 1, links: {} };
+}
+/**
+ * The stored binding for a project and origin, if any.
+ *
+ * @param projectRoot - Project root.
+ * @param apiUrl - API URL (any URL on the origin).
+ * @returns The binding, or `null`.
+ */
+export function readNexusProjectLink(projectRoot, apiUrl) {
+    return readLinkFile(nexusLinkPath(projectRoot)).links[new URL(apiUrl).origin] ?? null;
+}
+/** Map an API failure to a Nexus error; a 401 means the session expired. */
+function toLinkError(err) {
+    if (err instanceof NexusError) {
+        if (err.status === 401) {
+            return new NexusAccountError('E_NEXUS_SESSION_EXPIRED', 'the Nexus session expired or was revoked', 'run `cleo login nexus` again');
+        }
+        const remedy = typeof err.details?.['remedy'] === 'string' ? err.details['remedy'] : undefined;
+        return new NexusAccountError('E_NEXUS_REQUEST_FAILED', err.message, remedy);
+    }
+    return err instanceof Error ? err : new Error(String(err));
+}
+/**
+ * Register the project with Nexus (label only, never a path) and persist the
+ * binding in `.cleo/nexus-link.json`. Idempotent.
+ *
+ * @param opts - Project root, label, API URL, store and test overrides.
+ * @returns The binding and whether it already existed.
+ * @throws {NexusAccountError} Not signed in, expired session, invalid label,
+ *   not a CLEO project, or an API refusal (e.g. the id belongs to another account).
+ */
+export async function linkProjectToNexus(opts = {}) {
+    const apiUrl = resolveNexusApiUrl(opts.apiUrl);
+    const store = opts.store ?? new FileNexusTokenStore();
+    const session = await requireNexusSession(apiUrl, store);
+    let projectRoot;
+    try {
+        projectRoot = resolveOrCwd(opts.projectRoot);
+    }
+    catch {
+        throw new NexusAccountError('E_NEXUS_NOT_A_PROJECT', 'not inside a CLEO project', 'run `cleo init` first');
+    }
+    const identity = readDeclaredProjectIdentity(projectRoot);
+    if (!identity) {
+        throw new NexusAccountError('E_NEXUS_NOT_A_PROJECT', 'this project has no project id (.cleo/project-id)', 'run `cleo init` or `cleo upgrade` to assign one');
+    }
+    const projectId = identity.projectId;
+    const label = resolveLinkLabel(projectRoot, opts.label);
+    const http = new Http({
+        baseUrl: apiUrl,
+        token: session.bearer(),
+        ...(opts.fetch ? { fetch: opts.fetch } : {}),
+    });
+    let registered;
+    try {
+        registered = await registerProject(http, { projectId, label });
+    }
+    catch (err) {
+        throw toLinkError(err);
+    }
+    const linkPath = nexusLinkPath(projectRoot);
+    const link = {
+        apiUrl,
+        localProjectId: projectId,
+        remoteProjectId: registered.project.projectId,
+        organizationId: registered.project.organizationId,
+        label: registered.project.label,
+        streamId: registered.streamId,
+        linkedAt: new Date().toISOString(),
+    };
+    // Locked read-modify-write: concurrent links (other origins, other shells)
+    // never drop each other's entries. withLock needs a parseable file to read,
+    // so seed an empty one exclusively ('wx') when there is none.
+    try {
+        writeFileSync(linkPath, `${JSON.stringify({ version: 1, links: {} })}\n`, { flag: 'wx' });
+    }
+    catch (err) {
+        if (!(err instanceof Error && 'code' in err && err.code === 'EEXIST'))
+            throw err;
+    }
+    await withLock(linkPath, (current) => {
+        const parsed = linkFileSchema.safeParse(current);
+        const links = parsed.success ? parsed.data.links : {};
+        return { version: 1, links: { ...links, [apiUrl]: link } };
+    });
+    return {
+        link,
+        alreadyLinked: !registered.created,
+        linkPath,
+    };
+}
+//# sourceMappingURL=nexus-link.js.map

package/dist/cloud/nexus-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-link.js","sourceRoot":"","sources":["../../src/cloud/nexus-link.ts"],"names":[],"mappings":"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"}

package/dist/cloud/presence.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Replica presence mapper (T12721): one fleet-view location → the path-free
+ * `ReplicaPresence` the cleo-nexus cloud accepts at
+ * `PUT /v1/projects/:projectId/replicas/:replicaId/presence`.
+ *
+ * Pure: no I/O, no clock. Everything the contract marks **device-local, never
+ * mirrored** — path, hostname, remote name and URL, upstream ref, HEAD and
+ * upstream commit shas, probe error text — is read only to derive a boolean,
+ * a count or an enum, and never copied. `branch` is copied only when the
+ * caller opts in.
+ *
+ * @task T12721
+ * @epic T12496
+ */
+import { type NexusFleetDevice, type NexusFleetGitSummary, type NexusFleetLocation } from '@cleocode/contracts';
+import type { ReplicaPresence } from '@cleocode/contracts/cloud';
+/** The `git` block of a {@link ReplicaPresence}. */
+export type ReplicaPresenceGit = NonNullable<ReplicaPresence['git']>;
+/** The remote tracking state a presence reports. */
+export type ReplicaRemoteState = ReplicaPresenceGit['remote'];
+/** Server-side length limits of `ReplicaPresence` string fields. */
+export declare const REPLICA_PRESENCE_LIMITS: {
+    /** `git.branch` maximum length. */
+    readonly branchMax: 200;
+    /** `cliVersion` maximum length. */
+    readonly cliVersionMax: 40;
+};
+/** `cliVersion` sent when the device never reported its CLEO version. */
+export declare const UNKNOWN_CLI_VERSION = "unknown";
+/** Options for {@link toReplicaPresence}. */
+export interface ToReplicaPresenceOptions {
+    /** Include the checked-out branch (truncated to 200). Default `false`: branch names can be sensitive. */
+    includeBranch?: boolean;
+    /** Presence schema version. Default {@link NEXUS_FLEET_SCHEMA_VERSION}. */
+    schemaVersion?: number;
+}
+/**
+ * Remote tracking state of one probe row, as the presence enum.
+ *
+ * - a real probe failure (path missing or unreadable, not a repo, git error or
+ *   timeout) → `unknown`. `E_FETCH_FAILED` is NOT one: an offline `--fetch`
+ *   still recorded valid local ahead/behind as of the LAST fetch, so it maps
+ *   exactly like a probe that never fetched;
+ * - no upstream → `no-upstream`;
+ * - an upstream whose tracking ref is gone (`remote.headSha` null — e.g. the
+ *   branch was deleted remotely and pruned) or whose ahead/behind git did not
+ *   report → `unknown`, never a defaulted `in-sync`;
+ * - never fetched (`fetchedAt` null) → `unknown`;
+ * - otherwise from ahead/behind as of the last fetch: both → `diverged`,
+ *   ahead only → `ahead`, behind only → `behind`, neither → `in-sync`.
+ *
+ * @param git - Recorded git summary of the location.
+ * @returns The presence remote state.
+ * @example
+ * ```ts
+ * replicaRemoteState(summary); // 'behind'
+ * ```
+ */
+export declare function replicaRemoteState(git: NexusFleetGitSummary): ReplicaRemoteState;
+/**
+ * Map one fleet-view location on one device to the cloud `ReplicaPresence`.
+ *
+ * - `observedAt` is the probe instant (`git.probedAt`); an unprobed location
+ *   has no `git` block and reports when it was last encountered (`lastSeen`).
+ * - `cliVersion` is `device.cleoVersion` truncated to 40, or `unknown`.
+ * - `git.dirty` is `(dirtyCount ?? 0) + (untrackedCount ?? 0) > 0`;
+ *   `ahead`/`behind` default to 0; `remote` is {@link replicaRemoteState};
+ *   `lastCommitAt` is `headCommittedAt` when known; `branch` only with
+ *   `includeBranch`, truncated to 200.
+ *
+ * The replica id is not part of the body: it is the `:replicaId` path
+ * segment (`location.replicaId`), and a caller must not send presence while
+ * it is `null`.
+ *
+ * @param location - The location, from `nexus.projects.fleet`.
+ * @param device - The device holding it (same `deviceId`).
+ * @param opts - Branch opt-in and schema version.
+ * @returns A path-free presence body.
+ * @throws Error when `device.deviceId` differs from `location.deviceId`, or
+ *   when the observation instant (`git.probedAt`, else `lastSeen`) is not a
+ *   parseable timestamp — a raw string is never sent as `observedAt`.
+ * @example
+ * ```ts
+ * const body = toReplicaPresence(loc, device, { includeBranch: false });
+ * ```
+ */
+export declare function toReplicaPresence(location: NexusFleetLocation, device: NexusFleetDevice, opts?: ToReplicaPresenceOptions): ReplicaPresence;
+//# sourceMappingURL=presence.d.ts.map

package/dist/cloud/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../src/cloud/presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,oDAAoD;AACpD,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;AAErE,oDAAoD;AACpD,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AAE9D,oEAAoE;AACpE,eAAO,MAAM,uBAAuB;IAClC,mCAAmC;;IAEnC,mCAAmC;;CAE3B,CAAC;AAEX,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,yGAAyG;IACzG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,oBAAoB,GAAG,kBAAkB,CAUhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,gBAAgB,EACxB,IAAI,GAAE,wBAA6B,GAClC,eAAe,CAqCjB"}

package/dist/cloud/presence.js

@@ -0,0 +1,137 @@
+/**
+ * Replica presence mapper (T12721): one fleet-view location → the path-free
+ * `ReplicaPresence` the cleo-nexus cloud accepts at
+ * `PUT /v1/projects/:projectId/replicas/:replicaId/presence`.
+ *
+ * Pure: no I/O, no clock. Everything the contract marks **device-local, never
+ * mirrored** — path, hostname, remote name and URL, upstream ref, HEAD and
+ * upstream commit shas, probe error text — is read only to derive a boolean,
+ * a count or an enum, and never copied. `branch` is copied only when the
+ * caller opts in.
+ *
+ * @task T12721
+ * @epic T12496
+ */
+import { NEXUS_FLEET_SCHEMA_VERSION, } from '@cleocode/contracts';
+/** Server-side length limits of `ReplicaPresence` string fields. */
+export const REPLICA_PRESENCE_LIMITS = {
+    /** `git.branch` maximum length. */
+    branchMax: 200,
+    /** `cliVersion` maximum length. */
+    cliVersionMax: 40,
+};
+/** `cliVersion` sent when the device never reported its CLEO version. */
+export const UNKNOWN_CLI_VERSION = 'unknown';
+/**
+ * Remote tracking state of one probe row, as the presence enum.
+ *
+ * - a real probe failure (path missing or unreadable, not a repo, git error or
+ *   timeout) → `unknown`. `E_FETCH_FAILED` is NOT one: an offline `--fetch`
+ *   still recorded valid local ahead/behind as of the LAST fetch, so it maps
+ *   exactly like a probe that never fetched;
+ * - no upstream → `no-upstream`;
+ * - an upstream whose tracking ref is gone (`remote.headSha` null — e.g. the
+ *   branch was deleted remotely and pruned) or whose ahead/behind git did not
+ *   report → `unknown`, never a defaulted `in-sync`;
+ * - never fetched (`fetchedAt` null) → `unknown`;
+ * - otherwise from ahead/behind as of the last fetch: both → `diverged`,
+ *   ahead only → `ahead`, behind only → `behind`, neither → `in-sync`.
+ *
+ * @param git - Recorded git summary of the location.
+ * @returns The presence remote state.
+ * @example
+ * ```ts
+ * replicaRemoteState(summary); // 'behind'
+ * ```
+ */
+export function replicaRemoteState(git) {
+    if (git.probeErrorCode !== null && git.probeErrorCode !== 'E_FETCH_FAILED')
+        return 'unknown';
+    const { upstream, ahead, behind, headSha, fetchedAt } = git.remote;
+    if (upstream === null)
+        return 'no-upstream';
+    if (ahead === null || behind === null || headSha === null)
+        return 'unknown';
+    if (fetchedAt === null)
+        return 'unknown';
+    if (ahead > 0 && behind > 0)
+        return 'diverged';
+    if (ahead > 0)
+        return 'ahead';
+    if (behind > 0)
+        return 'behind';
+    return 'in-sync';
+}
+/**
+ * Map one fleet-view location on one device to the cloud `ReplicaPresence`.
+ *
+ * - `observedAt` is the probe instant (`git.probedAt`); an unprobed location
+ *   has no `git` block and reports when it was last encountered (`lastSeen`).
+ * - `cliVersion` is `device.cleoVersion` truncated to 40, or `unknown`.
+ * - `git.dirty` is `(dirtyCount ?? 0) + (untrackedCount ?? 0) > 0`;
+ *   `ahead`/`behind` default to 0; `remote` is {@link replicaRemoteState};
+ *   `lastCommitAt` is `headCommittedAt` when known; `branch` only with
+ *   `includeBranch`, truncated to 200.
+ *
+ * The replica id is not part of the body: it is the `:replicaId` path
+ * segment (`location.replicaId`), and a caller must not send presence while
+ * it is `null`.
+ *
+ * @param location - The location, from `nexus.projects.fleet`.
+ * @param device - The device holding it (same `deviceId`).
+ * @param opts - Branch opt-in and schema version.
+ * @returns A path-free presence body.
+ * @throws Error when `device.deviceId` differs from `location.deviceId`, or
+ *   when the observation instant (`git.probedAt`, else `lastSeen`) is not a
+ *   parseable timestamp — a raw string is never sent as `observedAt`.
+ * @example
+ * ```ts
+ * const body = toReplicaPresence(loc, device, { includeBranch: false });
+ * ```
+ */
+export function toReplicaPresence(location, device, opts = {}) {
+    if (device.deviceId !== location.deviceId) {
+        throw new Error(`toReplicaPresence: device ${device.deviceId} does not hold this location (device ${location.deviceId})`);
+    }
+    const observedRaw = location.git?.probedAt ?? location.lastSeen;
+    const observedAt = toUtcIso(observedRaw);
+    if (observedAt === undefined) {
+        throw new Error(`toReplicaPresence: observation instant ${JSON.stringify(observedRaw)} is not a valid ISO 8601 timestamp`);
+    }
+    const presence = {
+        cliVersion: truncate(device.cleoVersion ?? UNKNOWN_CLI_VERSION, REPLICA_PRESENCE_LIMITS.cliVersionMax),
+        schemaVersion: opts.schemaVersion ?? NEXUS_FLEET_SCHEMA_VERSION,
+        observedAt,
+    };
+    const git = location.git;
+    if (git === null)
+        return presence;
+    const block = {
+        dirty: (git.dirtyCount ?? 0) + (git.untrackedCount ?? 0) > 0,
+        ahead: git.remote.ahead ?? 0,
+        behind: git.remote.behind ?? 0,
+        remote: replicaRemoteState(git),
+    };
+    if (opts.includeBranch === true && git.branch !== null) {
+        block.branch = truncate(git.branch, REPLICA_PRESENCE_LIMITS.branchMax);
+    }
+    const lastCommitAt = git.headCommittedAt === null ? undefined : toUtcIso(git.headCommittedAt);
+    if (lastCommitAt !== undefined)
+        block.lastCommitAt = lastCommitAt;
+    presence.git = block;
+    return presence;
+}
+/** Truncate to `max` UTF-16 units without splitting a surrogate pair. */
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    const cut = value.slice(0, max);
+    const last = cut.charCodeAt(cut.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+}
+/** An instant as ISO 8601 UTC (`Z`), or `undefined` when unparsable. */
+function toUtcIso(value) {
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? undefined : new Date(ms).toISOString();
+}
+//# sourceMappingURL=presence.js.map

package/dist/cloud/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../../src/cloud/presence.ts"],"names":[],"mappings":"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"}

package/dist/cloud/projects.d.ts

@@ -4,10 +4,12 @@ import type { Http } from './http.js';
  * Register a project, or update its metadata when it is already registered. Organizations own
  * projects (ADR-095): pass `organizationId` to register into one the caller belongs to, or omit it
  * for the caller's personal organization. Re-registering into a different organization is refused
- * with `E_CONFLICT`. The server records no filesystem path.
+ * with `E_CONFLICT`. The server records no filesystem path. `created` is `true` on 201 (new
+ * registration) and `false` on 200 (the id was already registered; its label is updated).
  */
 export declare function registerProject(http: Http, req: RegisterProjectRequest): Promise<{
     project: Project;
     streamId: StreamId;
+    created: boolean;
 }>;
 //# sourceMappingURL=projects.d.ts.map

package/dist/cloud/projects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/cloud/projects.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,sBAAsB,EAE3B,KAAK,QAAQ,EACd,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,CAEnD"}
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/cloud/projects.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,sBAAsB,EAE3B,KAAK,QAAQ,EACd,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAQrE"}

package/dist/cloud/projects.js

@@ -3,9 +3,11 @@ import { RegisterProjectResult, } from '@cleocode/contracts/cloud';
  * Register a project, or update its metadata when it is already registered. Organizations own
  * projects (ADR-095): pass `organizationId` to register into one the caller belongs to, or omit it
  * for the caller's personal organization. Re-registering into a different organization is refused
- * with `E_CONFLICT`. The server records no filesystem path.
+ * with `E_CONFLICT`. The server records no filesystem path. `created` is `true` on 201 (new
+ * registration) and `false` on 200 (the id was already registered; its label is updated).
  */
 export async function registerProject(http, req) {
-    return http.request('POST', '/v1/projects', RegisterProjectResult, req);
+    const { data, status } = await http.requestWithStatus('POST', '/v1/projects', RegisterProjectResult, req);
+    return { ...data, created: status === 201 };
 }
 //# sourceMappingURL=projects.js.map

package/dist/cloud/projects.js.map

@@ -1 +1 @@
-{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../src/cloud/projects.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AAGnC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,GAA2B;IAE3B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,qBAAqB,EAAE,GAAG,CAAC,CAAC;AAC1E,CAAC"}
+{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../src/cloud/projects.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AAGnC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,GAA2B;IAE3B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,iBAAiB,CACnD,MAAM,EACN,cAAc,EACd,qBAAqB,EACrB,GAAG,CACJ,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,GAAG,EAAE,CAAC;AAC9C,CAAC"}

package/dist/cloud/uuidv7.d.ts

@@ -0,0 +1,9 @@
+/**
+ * UUIDv7 minting, kept free of other imports so the store's open path can use
+ * it without loading the cloud crypto module (T12341 row uids).
+ *
+ * @module
+ */
+/** A UUIDv7 (RFC 9562 §5.7): 48-bit Unix millis, then random bits. Mints checkpoint ids and row uids. */
+export declare function uuidv7(now?: number): string;
+//# sourceMappingURL=uuidv7.d.ts.map

package/dist/cloud/uuidv7.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuidv7.d.ts","sourceRoot":"","sources":["../../src/cloud/uuidv7.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,yGAAyG;AACzG,wBAAgB,MAAM,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAQvD"}

package/dist/cloud/uuidv7.js

@@ -0,0 +1,19 @@
+/**
+ * UUIDv7 minting, kept free of other imports so the store's open path can use
+ * it without loading the cloud crypto module (T12341 row uids).
+ *
+ * @module
+ */
+import { randomBytes } from 'node:crypto';
+/** A UUIDv7 (RFC 9562 §5.7): 48-bit Unix millis, then random bits. Mints checkpoint ids and row uids. */
+export function uuidv7(now = Date.now()) {
+    const b = randomBytes(16);
+    const ms = BigInt(Math.max(0, Math.floor(now)));
+    for (let i = 0; i < 6; i++)
+        b[i] = Number((ms >> BigInt(8 * (5 - i))) & 0xffn);
+    b[6] = ((b[6] ?? 0) & 0x0f) | 0x70;
+    b[8] = ((b[8] ?? 0) & 0x3f) | 0x80;
+    const h = b.toString('hex');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+//# sourceMappingURL=uuidv7.js.map

package/dist/cloud/uuidv7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuidv7.js","sourceRoot":"","sources":["../../src/cloud/uuidv7.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,yGAAyG;AACzG,MAAM,UAAU,MAAM,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IAC7C,MAAM,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QAAE,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,IAAI,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;IAC/E,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACnC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACnC,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC5B,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;AACnG,CAAC"}

package/dist/crypto/credentials.d.ts

@@ -75,11 +75,20 @@ export type ProjectCredentialKdf = 'project-id' | 'legacy-path';
  */
 export interface ProjectSecretContext extends CredentialKeyOptions {
     /**
-     * Stable project identity — the `projectId` of `.cleo/project-info.json`
-     * (or its tracked successor). Travels with the project directory, so a
-     * moved or renamed checkout derives the same key.
+     * Stable project identity — the declared id (`.cleo/project.json`, the
+     * legacy `.cleo/project-id`, else the `project-info.json` cache). Travels
+     * with the project directory, so a moved or renamed checkout derives the
+     * same key.
      */
     readonly projectId: string;
+    /**
+     * Ids this project was keyed by before (T12716): the `project-info.json`
+     * cache when it disagrees with the tracked id, and its
+     * `previousProjectIds` receipts. A project-id ciphertext sealed under one
+     * of them is opened and re-wrapped under {@link ProjectSecretContext.projectId},
+     * so re-keying a project never strands its credentials.
+     */
+    readonly previousProjectIds?: readonly string[];
     /**
      * Candidate project paths for ciphertexts still under the legacy path KDF
      * (typically the current root plus the path the registry last recorded).
@@ -123,7 +132,8 @@ export declare function encryptProjectSecret(plaintext: string, projectId: strin
 /**
  * Decrypt a project-scoped secret, migrating legacy ciphertexts on the way.
  *
- * - Version `0x02` ciphertexts open with the project-identity key.
+ * - Version `0x02` ciphertexts open with the project-identity key; one sealed
+ *   under a `previousProjectIds` entry is opened and re-wrapped (T12716).
  * - Version `0x01` (legacy, path-bound) ciphertexts are tried against each of
  *   `legacyProjectPaths`; the first that authenticates wins and the secret is
  *   re-encrypted under the project-identity KDF and returned as `rewrapped`

package/dist/crypto/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/crypto/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAqBH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,MAAsB,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAuID;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,IAAO,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,qCAAqC,IAAO,CAAC;AAK1D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,aAAa,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,oBAAoB,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AA2BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAyClC;AAyCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAiBjB"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/crypto/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAqBH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,MAAsB,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAuID;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,IAAO,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,qCAAqC,IAAO,CAAC;AAK1D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,aAAa,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,oBAAoB,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AA2BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAqDlC;AAyCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAiBjB"}

package/dist/crypto/credentials.js

@@ -232,7 +232,8 @@ export async function encryptProjectSecret(plaintext, projectId, options = {}) {
 /**
  * Decrypt a project-scoped secret, migrating legacy ciphertexts on the way.
  *
- * - Version `0x02` ciphertexts open with the project-identity key.
+ * - Version `0x02` ciphertexts open with the project-identity key; one sealed
+ *   under a `previousProjectIds` entry is opened and re-wrapped (T12716).
  * - Version `0x01` (legacy, path-bound) ciphertexts are tried against each of
  *   `legacyProjectPaths`; the first that authenticates wins and the secret is
  *   re-encrypted under the project-identity KDF and returned as `rewrapped`
@@ -250,6 +251,19 @@ export async function decryptProjectSecret(ciphertext, context) {
     if (parts.version === PROJECT_CIPHERTEXT_VERSION_PROJECT_ID) {
         const plaintext = openWithKey(parts, await deriveProjectIdKey(context.projectId, context.cleoHome));
         if (plaintext === null) {
+            // T12716: sealed under an id the project was re-keyed away from.
+            for (const previous of new Set(context.previousProjectIds ?? [])) {
+                if (previous.length === 0 || previous === context.projectId)
+                    continue;
+                const opened = openWithKey(parts, await deriveProjectIdKey(previous, context.cleoHome));
+                if (opened !== null) {
+                    return {
+                        plaintext: opened,
+                        kdf: 'project-id',
+                        rewrapped: await encryptProjectSecret(opened, context.projectId, context),
+                    };
+                }
+            }
             throw new Error(`Cannot decrypt project credential for project ${context.projectId}: ` +
                 'the machine key differs from the one that encrypted it (another device, or a ' +
                 'regenerated machine-key), or the data is corrupted.');