@neat.is/core 0.10.6-dev.20261007 → 0.10.6-dev.20261009

package/dist/registry.d.cts

@@ -0,0 +1,220 @@
+import { RegistryStatus, RegistryEntry, RegistryFile } from '@neat.is/types';
+
+/**
+ * Machine-level project registry + machine-wide daemon discovery.
+ *
+ * This module owns two surfaces under `~/.neat/`:
+ *
+ *  1. The legacy project registry at `~/.neat/projects.json` (ADR-048). One
+ *     file, per-user, machine-local, not synced. Under the project-daemon
+ *     contract (ADR-096) it is no longer the coordination point — it is read
+ *     once for migration and otherwise left to the additive writes the daemon
+ *     and orchestrator still perform. The read-modify-write helpers below keep
+ *     their atomic-write + exclusive-lock machinery for that legacy surface.
+ *
+ *  2. The machine-wide daemon discovery directory at `~/.neat/daemons/`
+ *     (ADR-096 §6). One file per running daemon — `<project>.json` — each owned
+ *     solely by the daemon that wrote it (on start) and removes it (on graceful
+ *     stop). Discovery is **append-only and lock-free**: a reader scans the
+ *     directory and reconciles liveness; it never acquires a shared lock, so it
+ *     can never deadlock against a daemon (#506). Losing or rebuilding the
+ *     directory costs discovery convenience, not correctness — each project's
+ *     own `neat-out/daemon.json` stays authoritative.
+ *
+ * `neat ps` / `neat list` and the per-daemon `pause` / `resume` / `uninstall`
+ * verbs read discovery, falling back to the legacy registry where no daemon
+ * file is present yet (the migration window before every daemon self-describes).
+ *
+ * The legacy lock is a file we exclusively-create (`O_EXCL`), hold while we
+ * mutate, and unlink on the way out. Crude but cross-platform; matches what
+ * `proper-lockfile` does internally without pulling the dep in. It never sits
+ * on the discovery path.
+ */
+
+declare function registryPath(): string;
+declare function registryLockPath(): string;
+interface DaemonPorts {
+    rest: number;
+    otlp: number;
+    web: number;
+}
+interface DaemonRecord {
+    project: string;
+    projectPath: string;
+    pid: number;
+    status: 'running' | 'stopped';
+    ports: DaemonPorts;
+    startedAt: string;
+    neatVersion: string;
+}
+interface DiscoveredDaemon {
+    record: DaemonRecord;
+    live: boolean;
+    source: string;
+}
+declare function daemonsDir(): string;
+declare function isPidAlive(pid: number): boolean;
+interface DiscoveryProbe {
+    isPidAlive(pid: number): boolean;
+}
+/**
+ * Scan `~/.neat/daemons/` and return every well-formed discovery record with
+ * its reconciled liveness. Lock-free: a plain directory read, no rendezvous.
+ *
+ * A missing directory (no daemon has ever started under this model) yields an
+ * empty list — first run, nothing to discover. Malformed or unreadable files
+ * are skipped silently; discovery degrades to "fewer entries," never an error.
+ */
+declare function discoverDaemons(probe?: DiscoveryProbe): Promise<DiscoveredDaemon[]>;
+/**
+ * Remove a daemon's discovery file. A daemon owns its own file, so this is for
+ * the per-daemon verbs reconciling a record whose daemon is gone (a crashed
+ * daemon that never cleared its own file) — never a rendezvous another process
+ * coordinates through. Best-effort: an already-absent file is success.
+ */
+declare function removeDaemonRecord(source: string): Promise<void>;
+interface MachineProject {
+    project: string;
+    projectPath: string;
+    state: 'running' | 'stopped' | 'registered';
+    ports?: DaemonPorts;
+    registryStatus?: RegistryStatus;
+    pid?: number;
+}
+/**
+ * The machine-wide project view the CLI verbs render. Discovery wins: every
+ * `~/.neat/daemons/` record becomes a row (running or stopped per liveness).
+ * Legacy registry entries whose path isn't already covered by a discovery
+ * record are folded in as `registered` rows so a pre-#508 install still lists
+ * its projects. Keyed on resolved path so a registry entry and its daemon
+ * record collapse to one row.
+ *
+ * Read-only on both surfaces. The registry is read once for migration; nothing
+ * here writes it back, in keeping with ADR-096 §8.
+ */
+declare function listMachineProjects(probe?: DiscoveryProbe): Promise<MachineProject[]>;
+declare function findDaemonByProject(name: string, probe?: DiscoveryProbe): Promise<DiscoveredDaemon | undefined>;
+declare function signalDaemonStop(pid: number): boolean;
+type LockHolder = {
+    kind: 'daemon';
+    pid: number;
+} | {
+    kind: 'command';
+    pid: number;
+} | {
+    kind: 'stale';
+};
+interface LockHolderProbe {
+    isPidAlive(pid: number): boolean;
+    daemonPidFromFile(): Promise<number | undefined>;
+    daemonResponds(): Promise<boolean>;
+}
+declare function classifyLockHolder(lockPath: string, probe?: LockHolderProbe): Promise<LockHolder>;
+declare function lockHolderMessage(holder: LockHolder, lockPath: string, timeoutMs: number): string;
+/**
+ * Path normalisation per ADR-048 #7. Two `init` calls from different relative
+ * paths to the same dir must collapse to one entry. `path.resolve` handles
+ * relative-to-cwd; we pass it through `fs.realpath` when the dir exists so
+ * symlinked paths land on the same canonical entry too.
+ */
+declare function normalizeProjectPath(input: string): Promise<string>;
+/**
+ * tmp + fsync + rename. The fsync on the data fd guarantees the bytes are on
+ * disk before rename swaps the inode; rename itself is atomic on POSIX.
+ *
+ * Exported so the init flow and test harnesses can use the same helper.
+ */
+declare function writeAtomically(target: string, contents: string): Promise<void>;
+/**
+ * Read the registry from disk. Returns an empty registry if the file does
+ * not exist yet — first run, never registered anything.
+ *
+ * Throws on parse / schema errors. The contract is single-source-of-truth;
+ * a corrupt file is louder than a silent reset.
+ */
+declare function readRegistry(): Promise<RegistryFile>;
+interface AddProjectOptions {
+    name: string;
+    path: string;
+    languages?: string[];
+    status?: RegistryStatus;
+}
+/**
+ * Anything the registry refuses to do.
+ *
+ * The identity lives on the class, not in the message text. Every caller that
+ * prints one already prefixes its own name — the CLI writes `neat: ` — so a
+ * message carrying `neat registry:` came out as `neat: neat registry: …`
+ * (#1240). A non-CLI caller that wants to know where an error came from reads
+ * `err.name`, which is more reliable than a string prefix anyway.
+ */
+declare class RegistryError extends Error {
+    constructor(message: string);
+}
+/** The registry lock could not be taken, and says who holds it. */
+declare class RegistryLockError extends RegistryError {
+    constructor(message: string);
+}
+declare class ProjectNameCollisionError extends RegistryError {
+    readonly projectName: string;
+    constructor(name: string);
+}
+/**
+ * Register a project, or update its `lastSeenAt` if the same path is already
+ * registered under the same name (idempotent re-init).
+ *
+ * Hard error on name collision against a different path — ADR-046 #7. The
+ * caller can recover by passing `--project <new-name>`.
+ */
+declare function addProject(opts: AddProjectOptions): Promise<RegistryEntry>;
+declare function getProject(name: string): Promise<RegistryEntry | undefined>;
+/**
+ * The registered project a directory belongs to: the entry whose path is `dir` itself,
+ * or failing that its nearest registered ancestor — so a verb run from `services/api`
+ * inside a registered repo still finds the repo. Paths are compared after the same
+ * normalisation registration applies (`normalizeProjectPath`), so a symlinked spelling
+ * of the directory matches the realpath the registry stored.
+ */
+declare function findProjectByPath(dir: string): Promise<RegistryEntry | undefined>;
+/**
+ * Synchronous startup lookup for stdio clients such as MCP. This keeps the
+ * registry file owned by this module while applying the same nearest-ancestor
+ * rule as findProjectByPath and the same discovery parser as the CLI.
+ */
+declare function registeredDaemonForPathSync(dir: string): {
+    registered: boolean;
+    restPort?: number;
+};
+declare function listProjects(): Promise<RegistryEntry[]>;
+declare function setStatus(name: string, status: RegistryStatus): Promise<RegistryEntry>;
+declare function touchLastSeen(name: string, at?: string): Promise<void>;
+/**
+ * Remove the registry entry for `name`. Per ADR-048 #6: this only removes the
+ * registry row. It does **not** touch `neat-out/`, `policy.json`, or any user
+ * file in the project directory. SDK-install rollback is a separate flow
+ * (`neat-rollback.patch`) that the caller opts in to.
+ */
+declare function removeProject(name: string): Promise<RegistryEntry | undefined>;
+declare const DEFAULT_PRUNE_TTL_MS: number;
+declare function pruneTtlMs(): number;
+type PathStatus = 'gone' | 'present' | 'unknown';
+interface PruneOptions {
+    ttlMs?: number;
+    statPath?: (p: string) => Promise<PathStatus>;
+    now?: () => number;
+}
+/**
+ * Remove registry entries whose `path` is definitely gone (ENOENT). Goes
+ * through the same lock + atomic-write path as every other mutation — never a
+ * raw rewrite — so the contract's atomicity invariant holds.
+ *
+ * Staleness gate: an ENOENT entry is dropped only when `ttlMs` is 0 (explicit
+ * `neat prune`) or its `lastSeenAt` (falling back to `registeredAt`) is older
+ * than `ttlMs`. A fresh ENOENT entry under a non-zero TTL is left in place — the
+ * daemon still marks it `broken`, the TTL is the safety margin before removal.
+ *
+ * Returns the entries that were removed.
+ */
+declare function pruneRegistry(opts?: PruneOptions): Promise<RegistryEntry[]>;
+
+export { type AddProjectOptions, DEFAULT_PRUNE_TTL_MS, type DaemonPorts, type DaemonRecord, type DiscoveredDaemon, type DiscoveryProbe, type LockHolder, type LockHolderProbe, type MachineProject, type PathStatus, ProjectNameCollisionError, type PruneOptions, RegistryError, RegistryLockError, addProject, classifyLockHolder, daemonsDir, discoverDaemons, findDaemonByProject, findProjectByPath, getProject, isPidAlive, listMachineProjects, listProjects, lockHolderMessage, normalizeProjectPath, pruneRegistry, pruneTtlMs, readRegistry, registeredDaemonForPathSync, registryLockPath, registryPath, removeDaemonRecord, removeProject, setStatus, signalDaemonStop, touchLastSeen, writeAtomically };

package/dist/registry.d.ts

@@ -0,0 +1,220 @@
+import { RegistryStatus, RegistryEntry, RegistryFile } from '@neat.is/types';
+
+/**
+ * Machine-level project registry + machine-wide daemon discovery.
+ *
+ * This module owns two surfaces under `~/.neat/`:
+ *
+ *  1. The legacy project registry at `~/.neat/projects.json` (ADR-048). One
+ *     file, per-user, machine-local, not synced. Under the project-daemon
+ *     contract (ADR-096) it is no longer the coordination point — it is read
+ *     once for migration and otherwise left to the additive writes the daemon
+ *     and orchestrator still perform. The read-modify-write helpers below keep
+ *     their atomic-write + exclusive-lock machinery for that legacy surface.
+ *
+ *  2. The machine-wide daemon discovery directory at `~/.neat/daemons/`
+ *     (ADR-096 §6). One file per running daemon — `<project>.json` — each owned
+ *     solely by the daemon that wrote it (on start) and removes it (on graceful
+ *     stop). Discovery is **append-only and lock-free**: a reader scans the
+ *     directory and reconciles liveness; it never acquires a shared lock, so it
+ *     can never deadlock against a daemon (#506). Losing or rebuilding the
+ *     directory costs discovery convenience, not correctness — each project's
+ *     own `neat-out/daemon.json` stays authoritative.
+ *
+ * `neat ps` / `neat list` and the per-daemon `pause` / `resume` / `uninstall`
+ * verbs read discovery, falling back to the legacy registry where no daemon
+ * file is present yet (the migration window before every daemon self-describes).
+ *
+ * The legacy lock is a file we exclusively-create (`O_EXCL`), hold while we
+ * mutate, and unlink on the way out. Crude but cross-platform; matches what
+ * `proper-lockfile` does internally without pulling the dep in. It never sits
+ * on the discovery path.
+ */
+
+declare function registryPath(): string;
+declare function registryLockPath(): string;
+interface DaemonPorts {
+    rest: number;
+    otlp: number;
+    web: number;
+}
+interface DaemonRecord {
+    project: string;
+    projectPath: string;
+    pid: number;
+    status: 'running' | 'stopped';
+    ports: DaemonPorts;
+    startedAt: string;
+    neatVersion: string;
+}
+interface DiscoveredDaemon {
+    record: DaemonRecord;
+    live: boolean;
+    source: string;
+}
+declare function daemonsDir(): string;
+declare function isPidAlive(pid: number): boolean;
+interface DiscoveryProbe {
+    isPidAlive(pid: number): boolean;
+}
+/**
+ * Scan `~/.neat/daemons/` and return every well-formed discovery record with
+ * its reconciled liveness. Lock-free: a plain directory read, no rendezvous.
+ *
+ * A missing directory (no daemon has ever started under this model) yields an
+ * empty list — first run, nothing to discover. Malformed or unreadable files
+ * are skipped silently; discovery degrades to "fewer entries," never an error.
+ */
+declare function discoverDaemons(probe?: DiscoveryProbe): Promise<DiscoveredDaemon[]>;
+/**
+ * Remove a daemon's discovery file. A daemon owns its own file, so this is for
+ * the per-daemon verbs reconciling a record whose daemon is gone (a crashed
+ * daemon that never cleared its own file) — never a rendezvous another process
+ * coordinates through. Best-effort: an already-absent file is success.
+ */
+declare function removeDaemonRecord(source: string): Promise<void>;
+interface MachineProject {
+    project: string;
+    projectPath: string;
+    state: 'running' | 'stopped' | 'registered';
+    ports?: DaemonPorts;
+    registryStatus?: RegistryStatus;
+    pid?: number;
+}
+/**
+ * The machine-wide project view the CLI verbs render. Discovery wins: every
+ * `~/.neat/daemons/` record becomes a row (running or stopped per liveness).
+ * Legacy registry entries whose path isn't already covered by a discovery
+ * record are folded in as `registered` rows so a pre-#508 install still lists
+ * its projects. Keyed on resolved path so a registry entry and its daemon
+ * record collapse to one row.
+ *
+ * Read-only on both surfaces. The registry is read once for migration; nothing
+ * here writes it back, in keeping with ADR-096 §8.
+ */
+declare function listMachineProjects(probe?: DiscoveryProbe): Promise<MachineProject[]>;
+declare function findDaemonByProject(name: string, probe?: DiscoveryProbe): Promise<DiscoveredDaemon | undefined>;
+declare function signalDaemonStop(pid: number): boolean;
+type LockHolder = {
+    kind: 'daemon';
+    pid: number;
+} | {
+    kind: 'command';
+    pid: number;
+} | {
+    kind: 'stale';
+};
+interface LockHolderProbe {
+    isPidAlive(pid: number): boolean;
+    daemonPidFromFile(): Promise<number | undefined>;
+    daemonResponds(): Promise<boolean>;
+}
+declare function classifyLockHolder(lockPath: string, probe?: LockHolderProbe): Promise<LockHolder>;
+declare function lockHolderMessage(holder: LockHolder, lockPath: string, timeoutMs: number): string;
+/**
+ * Path normalisation per ADR-048 #7. Two `init` calls from different relative
+ * paths to the same dir must collapse to one entry. `path.resolve` handles
+ * relative-to-cwd; we pass it through `fs.realpath` when the dir exists so
+ * symlinked paths land on the same canonical entry too.
+ */
+declare function normalizeProjectPath(input: string): Promise<string>;
+/**
+ * tmp + fsync + rename. The fsync on the data fd guarantees the bytes are on
+ * disk before rename swaps the inode; rename itself is atomic on POSIX.
+ *
+ * Exported so the init flow and test harnesses can use the same helper.
+ */
+declare function writeAtomically(target: string, contents: string): Promise<void>;
+/**
+ * Read the registry from disk. Returns an empty registry if the file does
+ * not exist yet — first run, never registered anything.
+ *
+ * Throws on parse / schema errors. The contract is single-source-of-truth;
+ * a corrupt file is louder than a silent reset.
+ */
+declare function readRegistry(): Promise<RegistryFile>;
+interface AddProjectOptions {
+    name: string;
+    path: string;
+    languages?: string[];
+    status?: RegistryStatus;
+}
+/**
+ * Anything the registry refuses to do.
+ *
+ * The identity lives on the class, not in the message text. Every caller that
+ * prints one already prefixes its own name — the CLI writes `neat: ` — so a
+ * message carrying `neat registry:` came out as `neat: neat registry: …`
+ * (#1240). A non-CLI caller that wants to know where an error came from reads
+ * `err.name`, which is more reliable than a string prefix anyway.
+ */
+declare class RegistryError extends Error {
+    constructor(message: string);
+}
+/** The registry lock could not be taken, and says who holds it. */
+declare class RegistryLockError extends RegistryError {
+    constructor(message: string);
+}
+declare class ProjectNameCollisionError extends RegistryError {
+    readonly projectName: string;
+    constructor(name: string);
+}
+/**
+ * Register a project, or update its `lastSeenAt` if the same path is already
+ * registered under the same name (idempotent re-init).
+ *
+ * Hard error on name collision against a different path — ADR-046 #7. The
+ * caller can recover by passing `--project <new-name>`.
+ */
+declare function addProject(opts: AddProjectOptions): Promise<RegistryEntry>;
+declare function getProject(name: string): Promise<RegistryEntry | undefined>;
+/**
+ * The registered project a directory belongs to: the entry whose path is `dir` itself,
+ * or failing that its nearest registered ancestor — so a verb run from `services/api`
+ * inside a registered repo still finds the repo. Paths are compared after the same
+ * normalisation registration applies (`normalizeProjectPath`), so a symlinked spelling
+ * of the directory matches the realpath the registry stored.
+ */
+declare function findProjectByPath(dir: string): Promise<RegistryEntry | undefined>;
+/**
+ * Synchronous startup lookup for stdio clients such as MCP. This keeps the
+ * registry file owned by this module while applying the same nearest-ancestor
+ * rule as findProjectByPath and the same discovery parser as the CLI.
+ */
+declare function registeredDaemonForPathSync(dir: string): {
+    registered: boolean;
+    restPort?: number;
+};
+declare function listProjects(): Promise<RegistryEntry[]>;
+declare function setStatus(name: string, status: RegistryStatus): Promise<RegistryEntry>;
+declare function touchLastSeen(name: string, at?: string): Promise<void>;
+/**
+ * Remove the registry entry for `name`. Per ADR-048 #6: this only removes the
+ * registry row. It does **not** touch `neat-out/`, `policy.json`, or any user
+ * file in the project directory. SDK-install rollback is a separate flow
+ * (`neat-rollback.patch`) that the caller opts in to.
+ */
+declare function removeProject(name: string): Promise<RegistryEntry | undefined>;
+declare const DEFAULT_PRUNE_TTL_MS: number;
+declare function pruneTtlMs(): number;
+type PathStatus = 'gone' | 'present' | 'unknown';
+interface PruneOptions {
+    ttlMs?: number;
+    statPath?: (p: string) => Promise<PathStatus>;
+    now?: () => number;
+}
+/**
+ * Remove registry entries whose `path` is definitely gone (ENOENT). Goes
+ * through the same lock + atomic-write path as every other mutation — never a
+ * raw rewrite — so the contract's atomicity invariant holds.
+ *
+ * Staleness gate: an ENOENT entry is dropped only when `ttlMs` is 0 (explicit
+ * `neat prune`) or its `lastSeenAt` (falling back to `registeredAt`) is older
+ * than `ttlMs`. A fresh ENOENT entry under a non-zero TTL is left in place — the
+ * daemon still marks it `broken`, the TTL is the safety margin before removal.
+ *
+ * Returns the entries that were removed.
+ */
+declare function pruneRegistry(opts?: PruneOptions): Promise<RegistryEntry[]>;
+
+export { type AddProjectOptions, DEFAULT_PRUNE_TTL_MS, type DaemonPorts, type DaemonRecord, type DiscoveredDaemon, type DiscoveryProbe, type LockHolder, type LockHolderProbe, type MachineProject, type PathStatus, ProjectNameCollisionError, type PruneOptions, RegistryError, RegistryLockError, addProject, classifyLockHolder, daemonsDir, discoverDaemons, findDaemonByProject, findProjectByPath, getProject, isPidAlive, listMachineProjects, listProjects, lockHolderMessage, normalizeProjectPath, pruneRegistry, pruneTtlMs, readRegistry, registeredDaemonForPathSync, registryLockPath, registryPath, removeDaemonRecord, removeProject, setStatus, signalDaemonStop, touchLastSeen, writeAtomically };

package/dist/registry.js

@@ -0,0 +1,62 @@
+import {
+  DEFAULT_PRUNE_TTL_MS,
+  ProjectNameCollisionError,
+  RegistryError,
+  RegistryLockError,
+  addProject,
+  classifyLockHolder,
+  daemonsDir,
+  discoverDaemons,
+  findDaemonByProject,
+  findProjectByPath,
+  getProject,
+  isPidAlive,
+  listMachineProjects,
+  listProjects,
+  lockHolderMessage,
+  normalizeProjectPath,
+  pruneRegistry,
+  pruneTtlMs,
+  readRegistry,
+  registeredDaemonForPathSync,
+  registryLockPath,
+  registryPath,
+  removeDaemonRecord,
+  removeProject,
+  setStatus,
+  signalDaemonStop,
+  touchLastSeen,
+  writeAtomically
+} from "./chunk-RGYC5U2Q.js";
+import "./chunk-MR64ICXX.js";
+export {
+  DEFAULT_PRUNE_TTL_MS,
+  ProjectNameCollisionError,
+  RegistryError,
+  RegistryLockError,
+  addProject,
+  classifyLockHolder,
+  daemonsDir,
+  discoverDaemons,
+  findDaemonByProject,
+  findProjectByPath,
+  getProject,
+  isPidAlive,
+  listMachineProjects,
+  listProjects,
+  lockHolderMessage,
+  normalizeProjectPath,
+  pruneRegistry,
+  pruneTtlMs,
+  readRegistry,
+  registeredDaemonForPathSync,
+  registryLockPath,
+  registryPath,
+  removeDaemonRecord,
+  removeProject,
+  setStatus,
+  signalDaemonStop,
+  touchLastSeen,
+  writeAtomically
+};
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}