@amoree-code/ocean 0.0.0-stage → 1.1.0

package/node_modules/@ocean/core/dist/shared/project-resolution.js

@@ -0,0 +1,1065 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { mkdir, readdir, readFile, realpath, rename, rmdir, writeFile, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { derivePrefix, formatTaskId, isValidPrefix, LEGACY_PREFIX, } from "../domain/tasks/task-id.js";
+import { atomicWrite, registryFile, withFileLock } from "./fs-utils.js";
+import { BRAIN_RECORD_DIRS, CHARTER_DIR, isWorkspaceProject, listProjectDirs, oceanEnv, oceanPath, oceanRoot, PROJECTS_DIR, projectDir, projectFolder, SYSTEM_DIR, WORKSPACE_PROJECT_ID, } from "./paths.js";
+export function projectConfirmationQuestion(resolution) {
+    if (resolution.status === "bound")
+        return null;
+    if (resolution.status === "ambiguous")
+        return "Which Ocean project should this request use? Specify the project name or binding path.";
+    return "Which Ocean project should this request use? Provide the project name and path to bind it.";
+}
+function bindingsFile() {
+    return registryFile("project-bindings.json");
+}
+export function findGitRoot(startDir) {
+    let dir = path.resolve(startDir);
+    while (true) {
+        if (existsSync(path.join(dir, ".git")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+// A linked worktree (`git worktree add`) has a `.git` file pointing into the main repo's
+// `.git/worktrees/<name>`; returns that main repo, or null for a normal repo or a submodule.
+export function linkedWorktreeMain(gitRoot) {
+    try {
+        const dotGit = path.join(gitRoot, ".git");
+        if (!statSync(dotGit).isFile())
+            return null;
+        const pointer = readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)$/m)?.[1];
+        if (!pointer)
+            return null;
+        const gitdir = path.resolve(gitRoot, pointer.trim());
+        const match = gitdir.match(/^(.*)[\\/]\.git[\\/]worktrees[\\/][^\\/]+$/);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+const execFileAsync = promisify(execFile);
+// `git status --short` lines for the repo containing `directory`; [] when it is not a repo or
+// git fails. --no-optional-locks: sessions share working trees, and a status that refreshes the
+// index would take index.lock and fail another session's concurrent add/commit (T-257).
+export async function gitChangedFiles(directory, timeout = 1_000) {
+    try {
+        const { stdout } = await execFileAsync("git", ["--no-optional-locks", "-C", directory, "status", "--short"], { timeout, maxBuffer: 1024 * 1024 });
+        return stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export const MAX_PROJECT_RULES = 10;
+export const MAX_PROJECT_RULE_BYTES = 200;
+export const MAX_PROJECT_VERIFY = 5;
+export const MAX_PROJECT_VERIFY_BYTES = 300;
+export const MAX_PROJECT_TAGS = 10;
+export const MAX_PROJECT_FORMER_PATHS = 20;
+const MANIFEST_FILE = "project.json";
+export function expandHome(value) {
+    if (value === "~")
+        return os.homedir();
+    if (value.startsWith("~/") || value.startsWith("~\\"))
+        return path.join(os.homedir(), value.slice(2));
+    return value;
+}
+export function portablePath(value) {
+    const home = os.homedir();
+    const resolved = path.resolve(value);
+    if (resolved === home)
+        return "~";
+    if (resolved.startsWith(`${home}${path.sep}`))
+        return `~/${path.relative(home, resolved).split(path.sep).join("/")}`;
+    return resolved;
+}
+import { isProjectCategory, isValidProjectId, PROJECT_CATEGORIES, PROJECT_CATEGORY_FOLDERS, UNCATEGORIZED, } from "../domain/context/project-id.js";
+export { isValidProjectId, PROJECT_CATEGORIES, UNCATEGORIZED, };
+// One spelling per directory: symlinks resolved (macOS /var is /private/var, and process.cwd()
+// returns the resolved form), so a bound path and the cwd of a session inside it compare equal.
+// A path that does not exist (a repo not cloned on this machine yet) is kept as written.
+export function canonicalPath(value) {
+    const resolved = path.resolve(expandHome(value));
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+function projectsRoot() {
+    return oceanPath(PROJECTS_DIR);
+}
+// The category folder a project folder sits in, or undefined while it is flat.
+function folderCategory(dir) {
+    const [first, second] = path.posix.relative(PROJECTS_DIR, dir).split("/");
+    return second && PROJECT_CATEGORY_FOLDERS.includes(first) ? first : undefined;
+}
+// Control characters (tab aside) and Unicode line breaks: a rule or command is one plain line.
+const LINE_BREAKING = /[\p{Cc}\u2028\u2029]/u;
+export function hasControlCharacters(value) {
+    return LINE_BREAKING.test(value.replace(/\t/g, " "));
+}
+function lineList(field, value, maxEntries, maxBytes) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`${field} must be a list of strings`);
+    if (value.length > maxEntries)
+        throw new Error(`${field} holds at most ${maxEntries} entries`);
+    return value.map((entry, index) => {
+        if (typeof entry !== "string" || !entry.trim())
+            throw new Error(`${field}[${index}] must be a non-empty string`);
+        const line = entry.trim();
+        if (hasControlCharacters(line))
+            throw new Error(`${field}[${index}] must be a single line without control characters`);
+        if (Buffer.byteLength(line, "utf8") > maxBytes)
+            throw new Error(`${field}[${index}] exceeds ${maxBytes} bytes`);
+        return line;
+    });
+}
+// The validated lists, or an Error naming the field.
+export function projectRules(manifest) {
+    return lineList("rules", manifest.rules, MAX_PROJECT_RULES, MAX_PROJECT_RULE_BYTES);
+}
+export function projectVerify(manifest) {
+    return lineList("verify", manifest.verify, MAX_PROJECT_VERIFY, MAX_PROJECT_VERIFY_BYTES);
+}
+export function projectTags(manifest) {
+    return lineList("tags", manifest.tags, MAX_PROJECT_TAGS, 40).map((tag) => tag.toLowerCase());
+}
+// The category, undefined when none is set, or an Error naming the allowed values.
+export function projectCategory(manifest) {
+    if (manifest.category === undefined)
+        return undefined;
+    if (!isProjectCategory(manifest.category))
+        throw new Error(`category must be one of ${PROJECT_CATEGORIES.join(", ")}`);
+    return manifest.category;
+}
+export function projectFormerPaths(manifest) {
+    return lineList("formerPaths", manifest.formerPaths, MAX_PROJECT_FORMER_PATHS, 500);
+}
+// `folder` is the project folder's name, `category` the category folder it sits in, if any.
+function parseManifest(folder, raw, category) {
+    const parsed = JSON.parse(raw);
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        !Array.isArray(parsed.paths) ||
+        parsed.paths.some((entry) => typeof entry !== "string" || !entry.trim()))
+        throw new Error("paths must be a list of non-empty strings");
+    if (parsed.prefix !== undefined &&
+        (typeof parsed.prefix !== "string" ||
+            parsed.prefix === LEGACY_PREFIX ||
+            !isValidPrefix(parsed.prefix)))
+        throw new Error(`prefix '${String(parsed.prefix)}' is not a valid task prefix`);
+    if (parsed.nextTask !== undefined &&
+        (!Number.isInteger(parsed.nextTask) || parsed.nextTask < 1))
+        throw new Error("nextTask must be a positive integer");
+    // The folder name is the id; a manifest cannot claim another project's identity.
+    return {
+        id: folder,
+        name: typeof parsed.name === "string" && parsed.name ? parsed.name : folder,
+        paths: parsed.paths,
+        created: typeof parsed.created === "string" ? parsed.created : "",
+        autoRegistered: parsed.autoRegistered === true,
+        ...(parsed.prefix !== undefined ? { prefix: parsed.prefix } : {}),
+        ...(parsed.nextTask !== undefined ? { nextTask: parsed.nextTask } : {}),
+        ...(parsed.rules !== undefined ? { rules: parsed.rules } : {}),
+        ...(parsed.verify !== undefined ? { verify: parsed.verify } : {}),
+        ...(parsed.tags !== undefined ? { tags: parsed.tags } : {}),
+        ...(parsed.formerPaths !== undefined
+            ? { formerPaths: parsed.formerPaths }
+            : {}),
+        ...(category === UNCATEGORIZED
+            ? {}
+            : category !== undefined
+                ? { category }
+                : parsed.category !== undefined
+                    ? { category: parsed.category }
+                    : {}),
+    };
+}
+// A broken project.json takes only its own project out of resolution: resolveProject runs in
+// every session's start hook, so one bad file must not break every project. The errors are
+// returned for `ocean project list` to report.
+export async function scanProjectManifests() {
+    const scan = { manifests: [], errors: [] };
+    const seen = new Set();
+    for (const { id, category, dir } of listProjectDirs()) {
+        const file = oceanPath(dir, MANIFEST_FILE);
+        // One id with project.json in two folders: the first, where projectDir looks first, is the
+        // project. A folder without project.json claims nothing.
+        if (seen.has(id)) {
+            if (existsSync(file))
+                scan.errors.push({
+                    file,
+                    error: `project id '${id}' is already used by another category folder`,
+                });
+            continue;
+        }
+        try {
+            scan.manifests.push(parseManifest(id, await readFile(file, "utf8"), category));
+            seen.add(id);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            seen.add(id);
+            scan.errors.push({
+                file,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return scan;
+}
+// One project's manifest, or null when it has none. A manifest that does not parse throws:
+// callers that must hold a project's rules fail closed instead of dropping them.
+export async function readProjectManifest(id, root = oceanRoot()) {
+    if (!isValidProjectId(id))
+        return null;
+    const dir = projectDir(id, root);
+    try {
+        return parseManifest(projectFolder(id), await readFile(path.join(root, dir, MANIFEST_FILE), "utf8"), folderCategory(dir));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function listProjectManifests() {
+    return (await scanProjectManifests()).manifests;
+}
+export async function writeManifest(manifest) {
+    const dir = projectDir(manifest.id);
+    const file = oceanPath(dir, MANIFEST_FILE);
+    // In a category folder the folder is the category; only a flat project keeps the field.
+    const { category, ...rest } = manifest;
+    const record = folderCategory(dir) === undefined && category !== undefined
+        ? manifest
+        : rest;
+    await mkdir(path.dirname(file), { recursive: true });
+    await atomicWrite(file, `${JSON.stringify(record, null, 2)}\n`);
+}
+// Bindings recorded before T-256, read from the flat registry file. Kept as a fallback until
+// `ocean project migrate --write` folds them into manifests, and rewritten as a cache after
+// every manifest change for anything that still reads the file. Entries the cache holds for
+// manifests are skipped, so a deleted project folder does not come back through it.
+// A corrupt file throws: resolution fails closed (no project, no task references) and writers
+// never overwrite what they cannot read. The session-start hook catches it on its own.
+async function listLegacyBindings() {
+    try {
+        const raw = await readFile(bindingsFile(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed?.bindings ?? []))
+            throw new Error(`${bindingsFile()}: bindings is not a list`);
+        return (parsed.bindings ?? []).filter((binding) => !binding.manifest);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+// gitRoot is left null here: resolution matches on paths, and walking up from every path of
+// every project on each session start would cost a filesystem walk per path for nothing.
+function manifestBindings(manifests) {
+    return manifests.flatMap((manifest) => manifest.paths.map((stored) => ({
+        id: manifest.id,
+        name: manifest.name,
+        path: canonicalPath(stored),
+        gitRoot: null,
+        boundAt: manifest.created,
+        manifest: true,
+    })));
+}
+function combineBindings(manifests, legacy) {
+    const fromManifests = manifestBindings(manifests);
+    const claimed = new Set(fromManifests.map((binding) => binding.path));
+    return [
+        ...fromManifests,
+        ...legacy
+            .map((binding) => ({ ...binding, path: canonicalPath(binding.path) }))
+            .filter((binding) => !claimed.has(binding.path)),
+    ];
+}
+export async function listProjectBindings() {
+    return combineBindings(await listProjectManifests(), await listLegacyBindings());
+}
+// The cache keeps every legacy entry, including ones a manifest now claims, so deleting that
+// manifest later never loses the old binding.
+function cacheBindings(manifests, legacy) {
+    return [...manifestBindings(manifests), ...legacy];
+}
+async function saveProjectBindings(bindings) {
+    const file = bindingsFile();
+    await mkdir(path.dirname(file), { recursive: true });
+    await atomicWrite(file, `${JSON.stringify({ version: 1, bindings }, null, 2)}\n`);
+}
+// One lock for every manifest/cache write: bindings are checked across all projects (a path
+// may belong to one project only), so per-project locks would let two writers both pass.
+export function withProjectsLock(run) {
+    return withFileLock(bindingsFile(), run);
+}
+// A manifest for a project seen for the first time. A folder with no tasks gets its own task
+// prefix and counter; one that already holds tasks stays on the legacy T namespace until
+// `ocean tasks renumber`. The workspace project is always T.
+async function newManifest(id, fields, others) {
+    const manifest = { id, ...fields };
+    if (isWorkspaceProject(id))
+        return manifest;
+    const tasks = await readdir(oceanPath(projectDir(id), "tasks")).catch(() => []);
+    if (tasks.some((entry) => !entry.startsWith(".")))
+        return manifest;
+    const taken = others.flatMap((other) => (other.prefix ? [other.prefix] : []));
+    return { ...manifest, prefix: derivePrefix(id, taken), nextTask: 1 };
+}
+export async function knownTaskPrefixes() {
+    const prefixes = (await listProjectManifests()).flatMap((manifest) => manifest.prefix ? [manifest.prefix] : []);
+    return [LEGACY_PREFIX, ...new Set(prefixes)];
+}
+// The project that owns a non-legacy prefix; null for T (the caller's own project) or a prefix
+// nobody uses. Two manifests claiming one prefix is a configuration error, never a guess.
+export async function projectForPrefix(prefix) {
+    if (prefix === LEGACY_PREFIX)
+        return null;
+    const owners = (await listProjectManifests())
+        .filter((manifest) => manifest.prefix === prefix)
+        .map((manifest) => manifest.id);
+    if (owners.length > 1)
+        throw new Error(`prefix ${prefix} is claimed by ${owners.join(", ")}; fix project.json`);
+    return owners[0] ?? null;
+}
+const TASK_NUMBER_SCAN_DEPTH = 2;
+// Highest <prefix>-<n> folder under every project's tasks/, live and archived. Archives are
+// tasks/archive/<namespace>/<id> (or flat archive/<id>), so descend archive/ two levels.
+// Every project is scanned because the legacy T sequence was shared by all of them.
+export async function highestTaskNumber(prefix) {
+    const pattern = new RegExp(`^${prefix}-(\\d+)$`);
+    let highest = 0;
+    const visit = async (directory, depth) => {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const match = pattern.exec(entry.name);
+            if (match)
+                highest = Math.max(highest, Number(match[1]));
+            else if (depth < TASK_NUMBER_SCAN_DEPTH &&
+                (depth > 0 || entry.name === "archive"))
+                await visit(path.join(directory, entry.name), depth + 1);
+        }
+    };
+    for (const { dir } of listProjectDirs())
+        await visit(oceanPath(dir, "tasks"), 0);
+    return highest;
+}
+async function nextTaskNumber(projectId) {
+    const folder = projectFolder(projectId);
+    const manifests = await listProjectManifests();
+    const manifest = manifests.find((candidate) => candidate.id === folder);
+    const prefix = manifest?.prefix ?? LEGACY_PREFIX;
+    // T is one namespace shared by every project without a prefix: each honours the highest
+    // counter among them, so numbers a renumber moved out of the scan are never reissued.
+    const floor = prefix === LEGACY_PREFIX
+        ? Math.max(1, ...manifests
+            .filter((candidate) => !candidate.prefix)
+            .map((candidate) => candidate.nextTask ?? 1))
+        : (manifest?.nextTask ?? 1);
+    const number = Math.max(floor, (await highestTaskNumber(prefix)) + 1);
+    return { prefix, number, manifest };
+}
+// The id the next task of this project would get. A prediction only: another writer may take
+// it before the caller writes, so a write goes through withNextTaskId.
+export async function peekNextTaskId(projectId) {
+    return withProjectsLock(async () => {
+        const next = await nextTaskNumber(projectId);
+        return formatTaskId(next.prefix, next.number);
+    });
+}
+// Issues the next id and runs the write under the projects lock, so two creators never get one
+// id. The counter advances only when the write succeeded; a refused write consumes nothing.
+export async function withNextTaskId(projectId, run) {
+    return withProjectsLock(async () => {
+        const next = await nextTaskNumber(projectId);
+        const result = await run(formatTaskId(next.prefix, next.number));
+        if (result.ok && next.manifest)
+            await writeManifest({ ...next.manifest, nextTask: next.number + 1 });
+        return result;
+    });
+}
+// Resolves the active Ocean project from a working directory: no terminal-in-Ocean
+// requirement. Match order is git root, then the exact cwd, then (as a last resort) whether
+// the path is inside the Ocean workspace root itself, which is always the workspace project.
+export async function resolveProject(cwd) {
+    const resolvedCwd = canonicalPath(cwd);
+    const gitRoot = findGitRoot(resolvedCwd);
+    const bindings = await listProjectBindings();
+    const containing = bindings
+        .filter((binding) => {
+        const bound = path.resolve(binding.path);
+        return (resolvedCwd === bound || resolvedCwd.startsWith(`${bound}${path.sep}`));
+    })
+        .sort((a, b) => path.resolve(b.path).length - path.resolve(a.path).length);
+    if (containing.length &&
+        (!containing[1] ||
+            path.resolve(containing[0].path).length >
+                path.resolve(containing[1].path).length)) {
+        const binding = containing[0];
+        return {
+            status: "bound",
+            projectId: binding.id,
+            name: binding.name,
+            path: binding.path,
+            matchedOn: path.resolve(binding.path) === resolvedCwd ? "cwd" : "path",
+            confidence: "high",
+        };
+    }
+    if (containing.length > 1)
+        return {
+            status: "ambiguous",
+            cwd: resolvedCwd,
+            candidates: containing,
+            confidence: "low",
+        };
+    const gitRootMatch = gitRoot
+        ? bindings.filter((binding) => path.resolve(binding.path) === gitRoot)
+        : [];
+    if (gitRootMatch.length === 1) {
+        return {
+            status: "bound",
+            projectId: gitRootMatch[0].id,
+            name: gitRootMatch[0].name,
+            path: gitRootMatch[0].path,
+            matchedOn: "git-root",
+            confidence: "high",
+        };
+    }
+    if (gitRootMatch.length > 1) {
+        return {
+            status: "ambiguous",
+            cwd: resolvedCwd,
+            candidates: gitRootMatch,
+            confidence: "low",
+        };
+    }
+    // A worktree beside its repo (house convention: <repo>-worktrees/<slug>) is that repo's project.
+    const main = gitRoot ? linkedWorktreeMain(gitRoot) : null;
+    if (main && main !== gitRoot) {
+        const viaMain = await resolveProject(main);
+        if (viaMain.status === "bound")
+            return viaMain;
+    }
+    const root = canonicalPath(oceanRoot());
+    const isFilesystemRoot = root === path.parse(root).root;
+    if (resolvedCwd === root ||
+        isFilesystemRoot ||
+        resolvedCwd.startsWith(`${root}${path.sep}`)) {
+        return {
+            status: "bound",
+            projectId: WORKSPACE_PROJECT_ID,
+            name: "Ocean",
+            path: root,
+            matchedOn: "ocean-root",
+            confidence: "high",
+        };
+    }
+    return { status: "unbound", cwd: resolvedCwd, gitRoot, confidence: "none" };
+}
+// Explicit registration/binding: never guesses on a name or path collision, always returns
+// the conflict instead of silently overwriting an existing binding. `addPath` is the one
+// deliberate exception: it adds another repo to an existing project (dashboard + backend).
+export async function bindProject(name, targetPath, options = {}) {
+    if (!isValidProjectId(name))
+        throw new Error(`Invalid project id '${name}': use lowercase letters, digits, dot, underscore or hyphen`);
+    const resolvedPath = canonicalPath(targetPath);
+    return withProjectsLock(async () => {
+        const manifests = await listProjectManifests();
+        const legacy = await listLegacyBindings();
+        const bindings = combineBindings(manifests, legacy);
+        const existingAtPath = bindings.find((binding) => path.resolve(binding.path) === resolvedPath);
+        if (existingAtPath && existingAtPath.id !== name)
+            return {
+                binding: existingAtPath,
+                created: false,
+                conflict: existingAtPath,
+            };
+        if (existingAtPath?.manifest)
+            return { binding: existingAtPath, created: false };
+        // From here the path is free, or is this project's own legacy binding being folded in,
+        // which is never a conflict.
+        const existingByName = bindings.find((binding) => binding.id === name && binding.path !== resolvedPath);
+        if (existingByName && !existingAtPath && !options.addPath)
+            return {
+                binding: existingByName,
+                created: false,
+                conflict: existingByName,
+            };
+        const existing = manifests.find((manifest) => manifest.id === name);
+        // Auto-registration never takes over a folder someone else made (checked under the lock,
+        // so a folder created a moment ago by another writer counts).
+        if (options.autoRegistered &&
+            !existing &&
+            existsSync(oceanPath(projectDir(name))))
+            throw new ProjectFolderTaken(`${projectDir(name)} already exists; bind it explicitly`);
+        const manifest = existing
+            ? { ...existing, paths: [...existing.paths, portablePath(resolvedPath)] }
+            : await newManifest(name, {
+                name,
+                paths: [portablePath(resolvedPath)],
+                created: new Date().toISOString(),
+                autoRegistered: options.autoRegistered === true,
+            }, manifests);
+        await writeManifest(manifest);
+        const updated = manifests
+            .filter((candidate) => candidate.id !== name)
+            .concat(manifest);
+        const next = combineBindings(updated, legacy);
+        await saveProjectBindings(cacheBindings(updated, legacy));
+        const binding = next.find((candidate) => candidate.path === resolvedPath);
+        return { binding, created: true };
+    });
+}
+// One-time fold of the legacy bindings file into manifests. Generic on purpose (the kernel is
+// public): a binding becomes a path of `04-projects/<id>/project.json` only when that project
+// folder exists; any other binding is reported and left alone, never turned into a new folder.
+export async function migrateProjectBindings(write) {
+    return withProjectsLock(async () => {
+        const legacy = await listLegacyBindings();
+        const manifests = await listProjectManifests();
+        const claimed = new Set(manifestBindings(manifests).map((binding) => binding.path));
+        const result = {
+            migrated: [],
+            orphaned: [],
+            written: write,
+        };
+        const updates = new Map();
+        for (const binding of legacy) {
+            const resolved = canonicalPath(binding.path);
+            if (claimed.has(resolved))
+                continue;
+            if (!isValidProjectId(binding.id)) {
+                result.orphaned.push({
+                    id: binding.id,
+                    path: resolved,
+                    reason: "id is not a valid project folder name; bind it explicitly",
+                });
+                continue;
+            }
+            const folder = oceanPath(projectDir(binding.id));
+            if (!existsSync(folder)) {
+                result.orphaned.push({
+                    id: binding.id,
+                    path: resolved,
+                    reason: `no project folder ${path.relative(oceanRoot(), folder)}; bind it explicitly`,
+                });
+                continue;
+            }
+            const base = updates.get(binding.id) ??
+                manifests.find((manifest) => manifest.id === binding.id) ??
+                (await newManifest(binding.id, {
+                    name: binding.name || binding.id,
+                    paths: [],
+                    created: binding.boundAt || new Date().toISOString(),
+                    autoRegistered: false,
+                }, [...manifests, ...updates.values()]));
+            updates.set(binding.id, {
+                ...base,
+                paths: [...base.paths, portablePath(resolved)],
+            });
+            claimed.add(resolved);
+            result.migrated.push({ id: binding.id, path: resolved });
+        }
+        if (write && updates.size) {
+            for (const manifest of updates.values())
+                await writeManifest(manifest);
+            await saveProjectBindings(cacheBindings(await listProjectManifests(), legacy));
+        }
+        return result;
+    });
+}
+const INDEX_BEGIN = "<!-- ocean:projects:begin (generated by `ocean project index --write`) -->";
+const INDEX_END = "<!-- ocean:projects:end -->";
+// Generated view of every project.json, kept in a managed block of 04-projects/registry.md so
+// the hand-kept rows around it are never rewritten.
+export async function renderProjectIndex() {
+    // Table cells: a `|` or a line break in a name or path would split the row.
+    const cell = (value) => value.replace(/[\r\n]+/g, " ").replaceAll("|", "\\|");
+    // One table per category, in PROJECT_CATEGORIES order; a project without one comes after,
+    // and a bad one shows as invalid instead of failing the whole index.
+    const category = (manifest) => {
+        try {
+            return projectCategory(manifest) ?? "uncategorized";
+        }
+        catch {
+            return "invalid";
+        }
+    };
+    const groups = new Map([...PROJECT_CATEGORIES, "uncategorized", "invalid"].map((name) => [
+        name,
+        [],
+    ]));
+    for (const manifest of await listProjectManifests())
+        groups
+            .get(category(manifest))
+            ?.push(`| \`${manifest.id}\` | ${cell(manifest.name)} | ${manifest.paths.length
+            ? manifest.paths.map((entry) => `\`${cell(entry)}\``).join("<br>")
+            : "—"} | ${manifest.autoRegistered ? "auto" : "manual"} |`);
+    const sections = [...groups]
+        .filter(([, rows]) => rows.length)
+        .flatMap(([name, rows]) => [
+        "",
+        `### ${name}`,
+        "",
+        "| Project | Name | Paths | Registered |",
+        "|---|---|---|---|",
+        ...rows,
+    ]);
+    return [
+        INDEX_BEGIN,
+        "## Projects (from project.json)",
+        ...sections,
+        INDEX_END,
+    ].join("\n");
+}
+export async function writeProjectIndex() {
+    return withProjectsLock(writeProjectIndexLocked);
+}
+async function writeProjectIndexLocked() {
+    const file = path.join(projectsRoot(), "registry.md");
+    let existing = "";
+    try {
+        existing = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const block = await renderProjectIndex();
+    const begin = existing.indexOf(INDEX_BEGIN);
+    const end = existing.indexOf(INDEX_END);
+    let next;
+    if (begin >= 0 && end > begin)
+        next = `${existing.slice(0, begin)}${block}${existing.slice(end + INDEX_END.length)}`;
+    else if (begin >= 0 || end >= 0)
+        throw new Error(`${file}: unmatched ocean:projects marker; fix it by hand before regenerating`);
+    else
+        next = existing
+            ? `${existing.replace(/\n*$/, "")}\n\n${block}\n`
+            : `# Project registry\n\n${block}\n`;
+    if (next === existing)
+        return { file, changed: false };
+    await mkdir(path.dirname(file), { recursive: true });
+    await atomicWrite(file, next);
+    return { file, changed: true };
+}
+// Where a session may register its repo as a project without being asked (T-256 phase 2).
+// OCEAN_CODE_ROOTS (a PATH-style list) overrides the default, ~/Documents.
+export function codeRoots() {
+    const configured = oceanEnv("CODE_ROOTS");
+    return (configured ? configured.split(path.delimiter) : ["~/Documents"])
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => path.resolve(expandHome(entry)));
+}
+// The existing project a client names (T-307): its id, or its name in any case (`LetSpeak` is
+// `letspeak`), or that name's slug. Never a guess beyond that.
+export function matchProject(manifests, ref) {
+    const name = ref.trim().toLowerCase();
+    const slug = projectSlug(ref);
+    return manifests.find((manifest) => manifest.id === ref ||
+        manifest.name.trim().toLowerCase() === name ||
+        (slug !== "" && manifest.id === slug))?.id;
+}
+// The names of the owner's Claude projects this machine has seen, as the always-on service last
+// wrote them (T-307): reading Claude Desktop's caches takes too long for a tool call.
+export function claudeProjectsFile() {
+    return oceanPath(SYSTEM_DIR, "state", "clients", "claude-projects.json");
+}
+export async function readClaudeProjects() {
+    try {
+        const parsed = JSON.parse(await readFile(claudeProjectsFile(), "utf8"));
+        return Array.isArray(parsed.names)
+            ? parsed.names.filter((name) => typeof name === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function findProject(ref) {
+    return matchProject(await listProjectManifests(), ref);
+}
+// A Claude project (claude.ai or Claude Desktop) first seen in a conversation (T-307): it has no
+// repo or path, so it is registered by name — 04-projects/<slug>/ with project.json, marked
+// auto-registered, and the standard layout. An existing project with that id or name is
+// returned instead; a folder that exists without a manifest is never taken over.
+export async function registerNamedProject(name, tags = []) {
+    return withProjectsLock(async () => {
+        const manifests = await listProjectManifests();
+        const known = matchProject(manifests, name);
+        if (known)
+            return { id: known, created: false };
+        const id = projectSlug(name);
+        if (!isValidProjectId(id))
+            throw new Error(`no usable project id from '${name}'`);
+        if (existsSync(oceanPath(projectDir(id))))
+            throw new ProjectFolderTaken(`${projectDir(id)}/ exists without project.json; register it explicitly`);
+        const manifest = await newManifest(id, {
+            name: name.trim(),
+            paths: [],
+            created: new Date().toISOString(),
+            autoRegistered: true,
+        }, manifests);
+        await writeManifest(tags.length ? { ...manifest, tags } : manifest);
+        await ensureProjectLayout(id);
+        await writeProjectIndexLocked();
+        return { id, created: true };
+    });
+}
+export function projectSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[^a-z0-9]+/, "")
+        .slice(0, 64)
+        .replace(/[-._]+$/, "");
+}
+async function realOrSelf(target) {
+    try {
+        return await realpath(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+function within(root, target) {
+    const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+    return target === root || target.startsWith(prefix);
+}
+class ProjectFolderTaken extends Error {
+}
+// A session opened in a git repo that no project claims registers that repo as its own
+// project: 04-projects/<slug>/ with project.json and the standard layout (ensureProjectLayout:
+// tasks/, memory/, docs/, MEMORY.md). Automatic runs stay
+// under the code roots, out of the temp dir and off a code root itself; `explicit` (the
+// `ocean project register` command) is the owner asking, so only the hard rules apply: a git
+// repo, not a linked worktree or submodule, not the Ocean workspace, never over an existing
+// project folder. Sibling repos are never merged: a code-root folder often holds unrelated
+// repos, so joining one project to another stays explicit (`bind --add`).
+export async function autoRegisterProject(cwd, options = {}) {
+    let resolution = options.resolution ?? (await resolveProject(cwd));
+    const skipped = (reason) => ({
+        status: "skipped",
+        reason,
+        resolution,
+    });
+    if (!options.explicit && oceanEnv("AUTO_REGISTER") === "0")
+        return skipped("disabled by OCEAN_AUTO_REGISTER=0");
+    if (resolution.status !== "unbound")
+        return skipped(`already ${resolution.status}`);
+    if (!resolution.gitRoot)
+        return skipped("not inside a git repository");
+    if (!statSync(path.join(resolution.gitRoot, ".git")).isDirectory())
+        return skipped("a linked worktree or submodule; bind it explicitly");
+    const repo = await realOrSelf(resolution.gitRoot);
+    if (within(await realOrSelf(oceanRoot()), repo))
+        return skipped("inside the Ocean workspace");
+    if (!options.explicit) {
+        const roots = await Promise.all(codeRoots().map(realOrSelf));
+        if (roots.includes(repo))
+            return skipped("is a code root itself");
+        const root = roots.find((candidate) => within(candidate, repo));
+        if (!root)
+            return skipped("outside the code roots");
+        // The temp dir is excluded unless the owner deliberately put a code root inside it.
+        const temp = await realOrSelf(os.tmpdir());
+        if (within(temp, repo) && !within(temp, root))
+            return skipped("inside the temp directory");
+    }
+    const id = projectSlug(path.basename(repo));
+    if (!isValidProjectId(id))
+        return skipped(`no usable id from '${repo}'`);
+    let result;
+    try {
+        result = await bindProject(id, resolution.gitRoot, {
+            autoRegistered: true,
+        });
+    }
+    catch (error) {
+        if (!(error instanceof ProjectFolderTaken))
+            throw error;
+        // Another session may have registered this very repo a moment ago.
+        resolution = await resolveProject(cwd);
+        return skipped(error.message);
+    }
+    if (result.conflict) {
+        resolution = await resolveProject(cwd);
+        return skipped(`conflicts with project '${result.conflict.id}'`);
+    }
+    await ensureProjectLayout(id);
+    resolution = {
+        status: "bound",
+        projectId: id,
+        name: id,
+        path: result.binding.path,
+        matchedOn: result.binding.path === path.resolve(cwd) ? "cwd" : "path",
+        confidence: "high",
+    };
+    return {
+        status: "registered",
+        projectId: id,
+        path: result.binding.path,
+        resolution,
+    };
+}
+function memoryHeading(id) {
+    return `# ${id} — memory`;
+}
+// The only entries a project folder holds at its root. Lessons and decisions go in memory/
+// (indexed by MEMORY.md, which every session in the project loads); reference material goes
+// in docs/ (indexed by docs/README.md); work goes in tasks/. index.md is the generated board.
+export const PROJECT_ROOT_ENTRIES = [
+    "project.json",
+    "MEMORY.md",
+    "README.md",
+    "index.md",
+    "tasks",
+    "memory",
+    "docs",
+];
+function memorySeed(id) {
+    return `${memoryHeading(id)}
+
+Index of this project's memory. Loaded only for sessions in this project.
+
+Layout — nothing else goes at the project root:
+- Lessons, decisions, gotchas → one file in \`memory/\`, plus one line here.
+- Reference material (requirements, API notes, plans, maps) → \`docs/\`, plus one line in \`docs/README.md\`.
+- Work → \`tasks/<ID>/task.md\`.
+`;
+}
+function docsHeading(id) {
+    return `# ${id} — docs`;
+}
+function docsSeed(id) {
+    return `${docsHeading(id)}
+
+Reference material for this project: requirements, API notes, plans, maps. One line per file
+below. Status lives in the tasks, never here.
+`;
+}
+// Creates whatever of the standard layout is missing and never overwrites a file. Returns the
+// paths it created, relative to the project folder.
+export async function ensureProjectLayout(projectId) {
+    const folder = oceanPath(projectDir(projectId));
+    const created = [];
+    for (const directory of ["tasks", "memory", "docs"])
+        if (await mkdir(path.join(folder, directory), { recursive: true }))
+            created.push(`${directory}/`);
+    const seeds = [
+        ["MEMORY.md", memorySeed(projectId)],
+        [path.join("docs", "README.md"), docsSeed(projectId)],
+    ];
+    for (const [file, text] of seeds) {
+        try {
+            await writeFile(path.join(folder, file), text, { flag: "wx" });
+            created.push(file.split(path.sep).join("/"));
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    return created;
+}
+// Undoes a binding (a wrong auto-registration, a moved repo). Only the path goes; the project
+// folder and its tasks stay, since deleting them is the owner's call.
+export async function unbindProjectPath(targetPath) {
+    const resolvedPath = canonicalPath(targetPath);
+    return withProjectsLock(async () => {
+        const manifests = await listProjectManifests();
+        const legacy = await listLegacyBindings();
+        // The binding whose path contains the given one, longest first, so `unbind .` works from
+        // anywhere inside the repo.
+        const removed = combineBindings(manifests, legacy)
+            .filter((binding) => within(path.resolve(binding.path), resolvedPath))
+            .sort((a, b) => b.path.length - a.path.length)[0] ?? null;
+        if (!removed)
+            return { removed };
+        const boundPath = path.resolve(removed.path);
+        const owner = manifests.find((manifest) => manifest.paths.some((stored) => canonicalPath(stored) === boundPath));
+        if (owner)
+            await writeManifest({
+                ...owner,
+                paths: owner.paths.filter((stored) => canonicalPath(stored) !== boundPath),
+            });
+        // A legacy entry for the same path would otherwise take the binding back.
+        const keptLegacy = legacy.filter((binding) => canonicalPath(binding.path) !== boundPath);
+        await saveProjectBindings(cacheBindings(await listProjectManifests(), keptLegacy));
+        return { removed };
+    });
+}
+// Workspace text that may name a project folder by path: the records, the projects, the charter.
+const REFERENCE_FILE = /\.(md|json|ya?ml|toml)$/i;
+const REFERENCE_MAX_BYTES = 2_000_000;
+// Rewrites `from` (a project folder relative to the Ocean root) to `to` in workspace text, as a
+// whole path: `04-projects/ocean` never touches `04-projects/ocean-ielts` or `ocean.md`, but
+// does match inside an absolute path and before a full stop. Dot folders are skipped. Returns
+// the files that change, relative to the Ocean root; writes them only when `write`.
+export async function rewriteProjectReferences(from, to, write) {
+    const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`(?<![A-Za-z0-9_.-])${escaped}(?![A-Za-z0-9_-]|\\.[A-Za-z0-9])`, "g");
+    const changed = [];
+    const visit = async (dir) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                await visit(file);
+            else if (entry.isFile() &&
+                REFERENCE_FILE.test(entry.name) &&
+                statSync(file).size <= REFERENCE_MAX_BYTES) {
+                const text = await readFile(file, "utf8");
+                const next = text.replace(pattern, to);
+                if (next === text)
+                    continue;
+                changed.push(path.relative(oceanRoot(), file).split(path.sep).join("/"));
+                if (write)
+                    await atomicWrite(file, next);
+            }
+        }
+    };
+    for (const root of new Set([...BRAIN_RECORD_DIRS, PROJECTS_DIR, CHARTER_DIR]))
+        await visit(oceanPath(root));
+    return changed.sort();
+}
+// Files a project under a category folder (T-311) and rewrites the workspace paths that name
+// its old folder. A dry run unless `write`: it reports the move and the files that would change.
+export async function moveProject(id, category, write = false) {
+    if (!isValidProjectId(id))
+        throw new Error("Project ids must be lowercase letters, digits, . _ or -");
+    if (!isProjectCategory(category))
+        throw new Error(`category must be one of ${PROJECT_CATEGORIES.join(", ")}`);
+    return withProjectsLock(async () => {
+        const manifest = (await listProjectManifests()).find((candidate) => candidate.id === projectFolder(id));
+        if (!manifest)
+            throw new Error(`No project.json for '${id}'`);
+        const from = projectDir(manifest.id);
+        const to = path.posix.join(PROJECTS_DIR, category, manifest.id);
+        if (from === to)
+            return { id: manifest.id, from, to, moved: false, references: [] };
+        if (existsSync(oceanPath(to)))
+            throw new Error(`${to} already exists`);
+        if (!write)
+            return {
+                id: manifest.id,
+                from,
+                to,
+                moved: false,
+                references: await rewriteProjectReferences(from, to, false),
+            };
+        await mkdir(path.dirname(oceanPath(to)), { recursive: true });
+        await rename(oceanPath(from), oceanPath(to));
+        // A category folder left empty goes; a flat project's written category is dropped.
+        if (folderCategory(from))
+            await rmdir(path.dirname(oceanPath(from))).catch(() => { });
+        await writeManifest(manifest);
+        const references = await rewriteProjectReferences(from, to, true);
+        if ((await readFile(path.join(projectsRoot(), "registry.md"), "utf8").catch(() => "")).includes(INDEX_BEGIN))
+            await writeProjectIndexLocked();
+        return { id: manifest.id, from, to, moved: true, references };
+    });
+}
+// Renames a project folder (fixes a wrong auto-registered id). Refused while the project has
+// tasks: their records carry the project id, and rewriting them belongs to phase 3.
+export async function renameProject(from, to) {
+    if (!isValidProjectId(from) || !isValidProjectId(to))
+        throw new Error("Project ids must be lowercase letters, digits, . _ or -");
+    return withProjectsLock(async () => {
+        // The project keeps its category folder.
+        const source = oceanPath(projectDir(from));
+        const target = path.join(path.dirname(source), to);
+        const manifest = (await listProjectManifests()).find((candidate) => candidate.id === from);
+        if (!manifest)
+            throw new Error(`No project.json for '${from}'`);
+        if (existsSync(target) || listProjectDirs().some(({ id }) => id === to))
+            throw new Error(`project '${to}' already exists`);
+        const tasks = await readdir(path.join(source, "tasks")).catch(() => []);
+        if (tasks.some((entry) => !entry.startsWith(".")))
+            throw new Error(`'${from}' has tasks; renaming a project with tasks is not supported yet`);
+        await rename(source, target);
+        await writeManifest({
+            ...manifest,
+            id: to,
+            name: manifest.name === from ? to : manifest.name,
+        });
+        for (const [file, heading] of [
+            ["MEMORY.md", memoryHeading],
+            [path.join("docs", "README.md"), docsHeading],
+        ]) {
+            const index = path.join(target, file);
+            try {
+                const text = await readFile(index, "utf8");
+                if (text.startsWith(heading(from)))
+                    await atomicWrite(index, `${heading(to)}${text.slice(heading(from).length)}`);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        if ((await readFile(path.join(projectsRoot(), "registry.md"), "utf8").catch(() => "")).includes(INDEX_BEGIN))
+            await writeProjectIndexLocked();
+        await saveProjectBindings(cacheBindings(await listProjectManifests(), await listLegacyBindings()));
+        return { from, to };
+    });
+}
+// Project folders under 04-projects that hold a tasks/ directory, sorted.
+export async function projectsWithTasks() {
+    const projects = [];
+    for (const { id, dir } of listProjectDirs()) {
+        try {
+            await readdir(oceanPath(dir, "tasks"));
+            projects.push(id);
+        }
+        catch {
+            /* no tasks/ here */
+        }
+    }
+    return [...new Set(projects)].sort();
+}
+// The project a folder belongs to, or null when it belongs to none. A registry that cannot be
+// read throws: no guessing which project a folder is.
+export async function folderProject(cwd) {
+    const resolution = await resolveProject(cwd);
+    return resolution.status === "bound" ? resolution.projectId : null;
+}
+//# sourceMappingURL=project-resolution.js.map