@cleocode/core 2026.9.23 → 2026.9.25

package/dist/nexus/registry.js

@@ -34,6 +34,8 @@ import { generateProjectHash } from './hash.js';
 import { collectCheckoutEvidence, legacyProjectId, projectPathFingerprint } from './identity.js';
 import { registryAliasClaimants, resolveProjectAlias } from './legacy-alias.js';
 import { isSupersededRegistryPath, recordCandidateLocation, recordProjectCheckout, } from './path-map.js';
+import { projectLastActivitySql } from './project-activity.js';
+import { NexusDeviceNotFoundError, NexusRegistryReadError, toRegistryReadError, } from './registry-errors.js';
 import { registryStorePath } from './registry-hygiene.js';
 // ── Path helpers ─────────────────────────────────────────────────────
 /** Get path to the NEXUS home directory (cache, etc.). */
@@ -96,6 +98,8 @@ function rowToProject(row) {
             : registryStorePath(row.projectPath),
         lastIndexed: row.lastIndexed ?? null,
         stats,
+        lastProbedAt: row.lastProbedAt ?? null,
+        lastOpenedAt: row.lastOpenedAt ?? null,
     };
 }
 /**
@@ -162,38 +166,40 @@ async function withLiveNexusDb(fn) {
 /**
  * Read all projects from nexus.db and return as a NexusRegistryFile.
  * Compatibility wrapper for consumers that expect the legacy JSON shape.
- * Returns null if nexus.db has not been initialized yet.
+ *
+ * @throws {NexusRegistryReadError} When the registry cannot be read — a
+ *   broken registry never looks empty (T12512).
  */
 export async function readRegistry() {
+    let rows;
     try {
-        const rows = await withLiveNexusDb((db) => db.select().from(projectRegistry));
-        const projects = {};
-        let latestUpdate = '';
-        for (const row of rows) {
-            const p = rowToProject(row);
-            projects[p.hash] = p;
-            if (p.lastSeen > latestUpdate)
-                latestUpdate = p.lastSeen;
-        }
-        return {
-            schemaVersion: '1.0.0',
-            lastUpdated: latestUpdate || new Date().toISOString(),
-            projects,
-        };
+        rows = await withLiveNexusDb((db) => db.select().from(projectRegistry));
     }
-    catch {
-        return null;
+    catch (error) {
+        throw toRegistryReadError('read registry', error);
+    }
+    const projects = {};
+    let latestUpdate = '';
+    for (const row of rows) {
+        const p = rowToProject(row);
+        projects[p.hash] = p;
+        if (p.lastSeen > latestUpdate)
+            latestUpdate = p.lastSeen;
     }
+    return {
+        schemaVersion: '1.0.0',
+        lastUpdated: latestUpdate || new Date().toISOString(),
+        projects,
+    };
 }
 /**
- * Read the global registry, throwing if not initialized.
+ * Read the global registry.
+ *
+ * @deprecated {@link readRegistry} now throws a typed error itself (T12512).
+ * @throws {NexusRegistryReadError} When the registry cannot be read.
  */
 export async function readRegistryRequired() {
-    const registry = await readRegistry();
-    if (!registry) {
-        throw new CleoError(ExitCode.NEXUS_NOT_INITIALIZED, 'Nexus registry not initialized. Run: cleo nexus init', { fix: 'cleo nexus init' });
-    }
-    return registry;
+    return readRegistry();
 }
 /**
  * Initialize the NEXUS directory structure and nexus.db.
@@ -234,29 +240,26 @@ async function readProjectMeta(projectPath) {
 /**
  * Read the declared immutable identity; absence differs from unreadable metadata.
  *
- * The local `project-info.json` id wins (ADR-094, T12325: local state
- * is keyed by it); a checkout that has not run `cleo init` yet declares the
- * tracked write-once `.cleo/project-id`, so a fresh clone never registers under
- * a path-derived fallback.
+ * The TRACKED id wins (T12470, T12716): `.cleo/project.json`, else the legacy
+ * `.cleo/project-id`, through `readPortableProjectId` — the same order as
+ * `readDeclaredProjectIdentity` and `decideProjectIdentity`. The
+ * `project-info.json` id is only a cache, used when nothing is tracked yet.
+ * A fresh clone that has not run `cleo init` therefore declares the tracked id
+ * and never registers under a path-derived fallback.
  */
 async function readProjectId(projectPath) {
     const infoPath = join(projectPath, '.cleo', 'project-info.json');
-    const tracked = () => {
-        const read = readPortableProjectId(projectPath);
-        return read.status === 'valid' ? read.projectId : '';
-    };
-    // T12470: the tracked `.cleo/project-id` outranks project-info.json.
-    const trackedId = tracked();
-    if (trackedId)
-        return trackedId;
+    const tracked = readPortableProjectId(projectPath);
+    if (tracked.status === 'valid')
+        return tracked.projectId;
     try {
         return (z
             .object({ projectId: z.string().min(1).optional() })
-            .parse(JSON.parse(await readFile(infoPath, 'utf8'))).projectId ?? tracked());
+            .parse(JSON.parse(await readFile(infoPath, 'utf8'))).projectId ?? '');
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
-            return tracked();
+            return '';
         throw new CleoError(ExitCode.CONFIG_ERROR, `Cannot read project identity at ${infoPath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
@@ -264,11 +267,12 @@ async function readProjectId(projectPath) {
  * Return the id a project root declares, adopting one first when it declares
  * none (T12470).
  *
- * A path — or any hash of it — is never a project identity. A root with
- * neither `.cleo/project-id` nor a `project-info.json` id gets one the same
- * way `cleo init` does: re-linked from the registry when exactly one
- * registered identity matches, otherwise freshly minted — and recorded
- * write-once in `.cleo/project-id`, so every later resolution returns it.
+ * A path — or any hash of it — is never a project identity. A root with no
+ * tracked identity (`.cleo/project.json` / `.cleo/project-id`) and no
+ * `project-info.json` id gets one the same way `cleo init` does: re-linked
+ * from the registry when exactly one registered identity matches, otherwise
+ * freshly minted — and recorded write-once in `.cleo/project.json` (plus the
+ * legacy `.cleo/project-id` mirror), so every later resolution returns it.
  *
  * @throws {CleoError} `CONFIG_ERROR` when no identity can be recorded.
  */
@@ -282,7 +286,7 @@ async function adoptDeclaredProjectId(projectPath) {
     const recorded = await readProjectId(projectPath);
     if (recorded)
         return recorded;
-    throw new CleoError(ExitCode.CONFIG_ERROR, `Project at ${projectPath} declares no identity and none could be recorded in .cleo/project-id; refusing to derive one from its path`, { fix: `Run \`cleo init\` in ${projectPath} to record the project's identity` });
+    throw new CleoError(ExitCode.CONFIG_ERROR, `Project at ${projectPath} declares no identity and none could be recorded in .cleo/project.json; refusing to derive one from its path`, { fix: `Run \`cleo init\` in ${projectPath} to record the project's identity` });
 }
 /** Record alternate project identity tokens as aliases for registry lookup. */
 async function recordProjectIdAliases(projectId, aliases, createdAt) {
@@ -340,6 +344,8 @@ export async function nexusRegister(projectRootOrPath, paramsOrName, permissions
             throw new CleoError(ExitCode.NOT_FOUND, `Path missing .cleo directory: ${resolvedPath}`);
         }
         const declaredId = await adoptDeclaredProjectId(resolvedPath);
+        const declared = readPortableProjectId(resolvedPath);
+        const declaredName = declared.status === 'valid' ? declared.name : undefined;
         const pathFingerprint = await projectPathFingerprint(resolvedPath);
         const evidence = await collectCheckoutEvidence(resolvedPath);
         await nexusInit();
@@ -362,13 +368,23 @@ export async function nexusRegister(projectRootOrPath, paramsOrName, permissions
             // Keyed by the primary key, so at most one row: no owner conflict exists.
             const existing = tx.select().from(projectRegistry).where(ownershipFilter).get();
             const immutableId = ownerId;
-            const projectName = name || existing?.name || basename(resolvedPath) || 'unnamed';
-            const nameOwner = tx
+            const takenByOther = (candidate) => tx
                 .select()
                 .from(projectRegistry)
-                .where(eq(projectRegistry.name, projectName))
-                .all();
-            if (nameOwner.some((row) => row.projectId !== immutableId)) {
+                .where(eq(projectRegistry.name, candidate))
+                .all()
+                .some((row) => row.projectId !== immutableId);
+            // T12716: an explicit name; else the row's current label (a repeat
+            // registration never silently relabels — `cleo doctor
+            // project-identity` reports drift and `--resolve` syncs it); else, for
+            // a new row, the committed `.cleo/project.json` name unless another
+            // project on this device already holds it; else the basename.
+            const projectName = name ||
+                existing?.name ||
+                (declaredName !== undefined && !takenByOther(declaredName) ? declaredName : '') ||
+                basename(resolvedPath) ||
+                'unnamed';
+            if (takenByOther(projectName)) {
                 throw new CleoError(ExitCode.VALIDATION_ERROR, `Project name '${projectName}' already exists in registry`);
             }
             const metadata = {
@@ -489,15 +505,19 @@ export async function nexusUnregister(projectRootOrNameOrHash, paramsOrUndefined
 }
 /**
  * List all registered projects.
+ *
+ * @throws {NexusRegistryReadError} When the registry cannot be read — never
+ *   an empty list that hides the failure (T12512).
  */
 export async function nexusList(_projectRoot = '', _params = {}) {
+    let rows;
     try {
-        const rows = await withLiveNexusDb((db) => db.select().from(projectRegistry));
-        return rows.map(rowToProject);
+        rows = await withLiveNexusDb((db) => db.select().from(projectRegistry));
     }
-    catch {
-        return [];
+    catch (error) {
+        throw toRegistryReadError('list projects', error);
     }
+    return rows.map(rowToProject);
 }
 /**
  * A project NAME matched more than one registry row (T12510). Names are not
@@ -513,7 +533,7 @@ export async function nexusList(_projectRoot = '', _params = {}) {
 export class NexusProjectAmbiguityError extends CleoError {
     /** Stable machine-readable error code. */
     codeName = 'E_NEXUS_PROJECT_AMBIGUOUS';
-    /** Every matching project, most recently seen first. */
+    /** Every matching project, most recently active first (`projectLastActivity`). */
     candidates;
     /**
      * @param name - The ambiguous project name, or alias key (T12589).
@@ -552,7 +572,8 @@ export async function nexusGetProject(projectRootOrNameOrHash, paramsOrUndefined
         // cross-project open can close mid-query.
         const row = await withLiveNexusDb(async (db) => {
             // T12469: the immutable id is the key, so it wins; a path hash is not
-            // unique, so among hash/name matches the most recently seen row wins.
+            // unique, so among hash/name matches the most recently active row wins
+            // (max of last_seen/last_opened_at/last_probed_at, T12512).
             let rows = await db
                 .select()
                 .from(projectRegistry)
@@ -562,7 +583,7 @@ export async function nexusGetProject(projectRootOrNameOrHash, paramsOrUndefined
                     .select()
                     .from(projectRegistry)
                     .where(eq(projectRegistry.projectHash, nameOrHash))
-                    .orderBy(desc(projectRegistry.lastSeen));
+                    .orderBy(desc(projectLastActivitySql));
             }
             if (rows.length === 0) {
                 // T12510: a name is not unique. One match resolves; several are
@@ -571,7 +592,7 @@ export async function nexusGetProject(projectRootOrNameOrHash, paramsOrUndefined
                     .select()
                     .from(projectRegistry)
                     .where(eq(projectRegistry.name, nameOrHash))
-                    .orderBy(desc(projectRegistry.lastSeen));
+                    .orderBy(desc(projectLastActivitySql));
                 if (rows.length > 1)
                     throw new NexusProjectAmbiguityError(nameOrHash, rows);
             }
@@ -584,7 +605,7 @@ export async function nexusGetProject(projectRootOrNameOrHash, paramsOrUndefined
                         .select()
                         .from(projectRegistry)
                         .where(inArray(projectRegistry.projectId, [...alias.claimants]))
-                        .orderBy(desc(projectRegistry.lastSeen));
+                        .orderBy(desc(projectLastActivitySql));
                     throw new NexusProjectAmbiguityError(nameOrHash, claimed, 'alias');
                 }
                 if (alias.status === 'resolved') {
@@ -601,9 +622,8 @@ export async function nexusGetProject(projectRootOrNameOrHash, paramsOrUndefined
         return rowToProject(row);
     }
     catch (error) {
-        if (error instanceof NexusProjectAmbiguityError)
-            throw error;
-        return null;
+        // T12512: `null` means "no such project", never "could not read".
+        throw toRegistryReadError('get project', error);
     }
 }
 /**
@@ -633,7 +653,8 @@ export async function nexusSync(projectRootOrName, paramsOrUndefined) {
         taskCount: meta.taskCount,
         labelsJson: JSON.stringify(meta.labels),
         lastSync: now,
-        lastSeen: now,
+        // T12512: a sync probes the project; it is not evidence of use.
+        lastProbedAt: now,
     })
         .where(eq(projectRegistry.projectId, project.projectId));
     await writeNexusAudit({
@@ -672,7 +693,7 @@ export async function nexusSyncAll() {
                 taskCount: meta.taskCount,
                 labelsJson: JSON.stringify(meta.labels),
                 lastSync: now,
-                lastSeen: now,
+                lastProbedAt: now,
             })
                 .where(eq(projectRegistry.projectId, project.projectId));
             synced++;
@@ -708,13 +729,13 @@ export async function nexusUpdateIndexStats(projectPath, stats) {
         const { getNexusDb } = await import('../store/nexus-sqlite.js');
         const { eq } = await import('drizzle-orm');
         const db = await getNexusDb();
-        // T12469: a path hash is not unique; the most recently seen row for this
+        // T12469: a path hash is not unique; the most recently active row for this
         // checkout is the one being indexed, and it is updated by its id.
         const ownerAt = async () => (await db
             .select({ projectId: projectRegistry.projectId })
             .from(projectRegistry)
             .where(eq(projectRegistry.projectHash, projectHash))
-            .orderBy(desc(projectRegistry.lastSeen))
+            .orderBy(desc(projectLastActivitySql))
             .limit(1))[0];
         let owner = await ownerAt();
         if (!owner) {
@@ -1045,10 +1066,26 @@ export { resetNexusDbState };
 // EngineResult-returning wrappers (T1569 / ADR-057 / ADR-058)
 // ---------------------------------------------------------------------------
 /**
- * Convert a caught error to an EngineResult failure.
+ * Convert a caught error to an EngineResult failure, keeping the code, exit
+ * code, fix and details of a typed registry error (`E_NEXUS_REGISTRY_READ`,
+ * `E_NEXUS_DEVICE_NOT_FOUND`, `E_NEXUS_PROJECT_AMBIGUOUS`, `E_PROJECT_MOVED`)
+ * instead of collapsing it to `E_INTERNAL` (T12512). Every nexus engine
+ * wrapper that reads the registry uses this.
+ *
+ * @param error - The caught value.
+ * @param fallbackMsg - Message used when `error` is not an `Error`.
+ * @returns A failed EngineResult.
+ * @example
+ * ```ts
+ * try { return engineSuccess(await nexusList()); }
+ * catch (error) { return nexusCaughtToEngineError(error, 'Failed to list projects'); }
+ * ```
+ * @task T12512
  */
-function caughtToEngineError(error, fallbackMsg) {
-    if (error instanceof NexusProjectAmbiguityError) {
+export function nexusCaughtToEngineError(error, fallbackMsg) {
+    if (error instanceof NexusProjectAmbiguityError ||
+        error instanceof NexusRegistryReadError ||
+        error instanceof NexusDeviceNotFoundError) {
         return engineError(error.codeName, error.message, {
             exitCode: error.code,
             details: error.details,
@@ -1075,17 +1112,16 @@ function caughtToEngineError(error, fallbackMsg) {
 // SSoT-EXEMPT:engine-migration-T1569
 export async function nexusStatus() {
     try {
+        // T12512: an unreadable registry is an error envelope, never "not initialized".
         const registry = await readRegistry();
-        const initialized = registry !== null;
-        const projectCount = initialized ? Object.keys(registry.projects).length : 0;
         return engineSuccess({
-            initialized,
-            projectCount,
-            lastUpdated: registry?.lastUpdated ?? null,
+            initialized: true,
+            projectCount: Object.keys(registry.projects).length,
+            lastUpdated: registry.lastUpdated,
         });
     }
     catch (error) {
-        return caughtToEngineError(error, 'Failed to get nexus status');
+        return nexusCaughtToEngineError(error, 'Failed to get nexus status');
     }
 }
 /**
@@ -1111,7 +1147,7 @@ export async function nexusListProjects(limit, offset) {
         };
     }
     catch (error) {
-        return caughtToEngineError(error, 'Failed to list projects');
+        return nexusCaughtToEngineError(error, 'Failed to list projects');
     }
 }
 /**
@@ -1129,7 +1165,7 @@ export async function nexusShowProject(name) {
         return engineSuccess(project);
     }
     catch (error) {
-        return caughtToEngineError(error, `Failed to show project: ${name}`);
+        return nexusCaughtToEngineError(error, `Failed to show project: ${name}`);
     }
 }
 /**
@@ -1144,7 +1180,7 @@ export async function nexusInitialize() {
         return engineSuccess({ message: 'NEXUS initialized successfully' });
     }
     catch (error) {
-        return caughtToEngineError(error, 'Failed to initialize nexus');
+        return nexusCaughtToEngineError(error, 'Failed to initialize nexus');
     }
 }
 /**
@@ -1159,7 +1195,7 @@ export async function nexusRegisterProject(path, name, permission = 'read') {
         return engineSuccess({ hash, message: `Project registered with hash: ${hash}` });
     }
     catch (error) {
-        return caughtToEngineError(error, `Failed to register project: ${path}`);
+        return nexusCaughtToEngineError(error, `Failed to register project: ${path}`);
     }
 }
 /**
@@ -1174,7 +1210,7 @@ export async function nexusUnregisterProject(name) {
         return engineSuccess({ message: `Project unregistered: ${name}` });
     }
     catch (error) {
-        return caughtToEngineError(error, `Failed to unregister project: ${name}`);
+        return nexusCaughtToEngineError(error, `Failed to unregister project: ${name}`);
     }
 }
 /**
@@ -1193,7 +1229,7 @@ export async function nexusSyncProject(name) {
         return engineSuccess(result);
     }
     catch (error) {
-        return caughtToEngineError(error, 'Failed to sync project');
+        return nexusCaughtToEngineError(error, 'Failed to sync project');
     }
 }
 /**
@@ -1208,7 +1244,7 @@ export async function nexusReconcileProject(projectRoot, params = {}) {
         return engineSuccess(result);
     }
     catch (error) {
-        return caughtToEngineError(error, `Failed to reconcile project: ${projectRoot}`);
+        return nexusCaughtToEngineError(error, `Failed to reconcile project: ${projectRoot}`);
     }
 }
 /**
@@ -1225,7 +1261,7 @@ export async function nexusProjectsList() {
         return engineSuccess({ projects: list, count: list.length, devices });
     }
     catch (error) {
-        return caughtToEngineError(error, 'Failed to list nexus projects');
+        return nexusCaughtToEngineError(error, 'Failed to list nexus projects');
     }
 }
 /**
@@ -1243,10 +1279,40 @@ export async function nexusProjectsStatus(_projectRoot, params) {
     try {
         const { getNexusRegistryDb } = await import('../store/nexus-sqlite.js');
         const { runProjectsGitStatus } = await import('./git-state.js');
-        return engineSuccess(await runProjectsGitStatus(await getNexusRegistryDb(getCleoHome()), params));
+        let db;
+        try {
+            db = await getNexusRegistryDb(getCleoHome());
+        }
+        catch (error) {
+            throw toRegistryReadError('open project registry', error);
+        }
+        return engineSuccess(await runProjectsGitStatus(db, params));
+    }
+    catch (error) {
+        return nexusCaughtToEngineError(error, 'Failed to probe project git state');
+    }
+}
+/**
+ * Fleet view (`nexus.projects.fleet`, T12513): every project, where it lives
+ * on each device, and its last recorded git state, paged with counts first.
+ * Read-only: it never runs git — see `nexus/fleet-status.ts`.
+ *
+ * @param _projectRoot - Unused: the fleet spans every registered project
+ *   (uniform ADR-057 signature).
+ * @param params - Filters, staleness window and paging.
+ * @returns The fleet view, or a typed error (`E_NEXUS_REGISTRY_READ`,
+ *   `E_NEXUS_DEVICE_NOT_FOUND`) — never an empty page that hides a failure.
+ * @task T12513
+ */
+export async function nexusProjectsFleet(_projectRoot, params) {
+    const { getNexusRegistryDb } = await import('../store/nexus-sqlite.js');
+    const { listFleetStatus } = await import('./fleet-status.js');
+    try {
+        return engineSuccess(listFleetStatus(await getNexusRegistryDb(getCleoHome()), params));
     }
     catch (error) {
-        return caughtToEngineError(error, 'Failed to probe project git state');
+        // A typed error (unknown device) passes through; anything else is a read failure.
+        return nexusCaughtToEngineError(toRegistryReadError('read fleet status', error), 'Failed to read fleet status');
     }
 }
 /**
@@ -1263,7 +1329,7 @@ export async function nexusProjectsRegister(repoPath, name) {
         return engineSuccess({ hash, path: repoPath });
     }
     catch (error) {
-        return caughtToEngineError(error, `Failed to register project: ${repoPath}`);
+        return nexusCaughtToEngineError(error, `Failed to register project: ${repoPath}`);
     }
 }
 /**
@@ -1279,7 +1345,7 @@ export async function nexusProjectsRemove(nameOrHash) {
         return engineSuccess({ removed: nameOrHash });
     }
     catch (error) {
-        return caughtToEngineError(error, `Failed to remove project: ${nameOrHash}`);
+        return nexusCaughtToEngineError(error, `Failed to remove project: ${nameOrHash}`);
     }
 }
 //# sourceMappingURL=registry.js.map