@amoree-code/ocean 0.0.0-stage → 1.2.0

package/node_modules/@ocean/loop/dist/tasks/claim-task.js

@@ -0,0 +1,126 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { localDate } from "@ocean/core/shared/local-date.js";
+import { resolveWithin } from "@ocean/core/shared/paths.js";
+// Keep equal to CLAIM_TTL_MS in scripts/validate-tasks.mjs (a test pins the two together).
+export const CLAIM_TTL_MS = 2 * 60 * 60 * 1000;
+const OWNER = /^[\w.@/-]{1,64}$/;
+const CLAIM_PATH = /^(?!\/)(?!.*\.\.)[\w.@/-]+$/;
+const unquote = (value) => value.replace(/^['"]|['"]$/g, "");
+function frontmatterFields(source) {
+    const end = source.indexOf("\n---", 4);
+    if (!source.startsWith("---\n") || end < 0)
+        return {};
+    const fields = {};
+    for (const line of source.slice(4, end).split("\n")) {
+        const separator = line.indexOf(":");
+        if (separator > 0 && /^[\w-]+$/.test(line.slice(0, separator)))
+            fields[line.slice(0, separator)] = line.slice(separator + 1).trim();
+    }
+    return fields;
+}
+function parseClaim(fields) {
+    if (!fields.claimed_by || !fields.claimed_at)
+        return null;
+    const list = fields.claimed_paths?.match(/^\[(.*)\]$/)?.[1] ?? "";
+    return {
+        by: unquote(fields.claimed_by),
+        at: unquote(fields.claimed_at),
+        paths: list
+            .split(",")
+            .map((entry) => normalizePath(unquote(entry.trim())))
+            .filter(Boolean),
+    };
+}
+const normalizePath = (value) => value.replace(/^\.\//, "").replace(/\/+$/, "");
+const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+export function isStale(claim, now = new Date()) {
+    const claimedAt = Date.parse(claim.at);
+    return Number.isNaN(claimedAt) || now.getTime() - claimedAt > CLAIM_TTL_MS;
+}
+// Replace the claim lines in the frontmatter (and bump `updated`), keeping every other line.
+function withClaim(source, claim, today) {
+    const end = source.indexOf("\n---", 4);
+    const kept = source
+        .slice(4, end)
+        .split("\n")
+        .filter((line) => !/^claimed_(by|at|paths):/.test(line))
+        .map((line) => (/^updated:/.test(line) ? `updated: ${today}` : line));
+    if (claim) {
+        kept.push(`claimed_by: ${claim.by}`, `claimed_at: ${claim.at}`);
+        if (claim.paths.length)
+            kept.push(`claimed_paths: [${claim.paths.join(", ")}]`);
+    }
+    return `---\n${kept.join("\n")}${source.slice(end)}`;
+}
+async function liveClaimsElsewhere(root, id, now) {
+    const found = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name === "archive" || entry.name === id)
+            continue;
+        const source = await readFile(resolveWithin(root, entry.name, "task.md"), "utf8").catch(() => "");
+        const claim = parseClaim(frontmatterFields(source));
+        if (claim && !isStale(claim, now))
+            found.push({ id: entry.name, claim });
+    }
+    return found;
+}
+/**
+ * Record that `by` is working on a task. Refuses (throws, naming the holder) when another
+ * owner holds a non-stale claim on it, or when `paths` overlap a non-stale claim another owner
+ * holds on a different task. The same owner re-claiming refreshes the timestamp. Claims are
+ * advisory: they make a collision visible, they do not lock the files.
+ */
+export async function claimTask(id, root, input) {
+    if (!OWNER.test(input.by))
+        throw new Error("--by must be 1-64 chars of letters, digits, . _ @ / -");
+    const paths = (input.paths ?? []).map(normalizePath).filter(Boolean);
+    for (const entry of paths)
+        if (!CLAIM_PATH.test(entry))
+            throw new Error(`Invalid claim path: ${entry}`);
+    const now = input.now ?? new Date();
+    const taskFile = resolveWithin(root, id, "task.md");
+    const source = await readFile(taskFile, "utf8");
+    const fields = frontmatterFields(source);
+    if (["done", "cancelled"].includes(fields.state))
+        throw new Error(`${id} is ${fields.state}; it cannot be claimed`);
+    const held = parseClaim(fields);
+    let tookOver;
+    if (held && held.by !== input.by && !isStale(held, now)) {
+        if (!input.force)
+            throw new Error(`${id} is claimed by ${held.by} since ${held.at}. Ask the owner, wait for it to expire (2 h), or use --force.`);
+        tookOver = held.by;
+    }
+    if (!input.force)
+        for (const other of await liveClaimsElsewhere(root, id, now)) {
+            if (other.claim.by === input.by)
+                continue;
+            const clash = paths.find((mine) => other.claim.paths.some((theirs) => overlaps(mine, theirs)));
+            if (clash)
+                throw new Error(`${clash} overlaps ${other.claim.paths.join(", ")} claimed by ${other.claim.by} on ${other.id}.`);
+        }
+    const claim = { by: input.by, at: now.toISOString(), paths };
+    await writeFile(taskFile, withClaim(source, claim, localDate(now)), "utf8");
+    // Read-modify-write is not atomic: if a concurrent claim landed between our read and write,
+    // the file now names someone else. Re-read so the loser finds out instead of assuming it won.
+    const written = parseClaim(frontmatterFields(await readFile(taskFile, "utf8")));
+    if (written?.by !== input.by)
+        throw new Error(`${id} was claimed by ${written?.by} at the same time.`);
+    return { claimed: id, by: claim.by, at: claim.at, tookOver };
+}
+/**
+ * Drop a task's claim. Only the owner may release a live claim (or `force`); a stale claim can
+ * be released by anyone. Returns `released: false` when there was nothing to release.
+ */
+export async function releaseTask(id, root, input) {
+    const now = input.now ?? new Date();
+    const taskFile = resolveWithin(root, id, "task.md");
+    const source = await readFile(taskFile, "utf8");
+    const held = parseClaim(frontmatterFields(source));
+    if (!held)
+        return { released: false, id };
+    if (held.by !== input.by && !isStale(held, now) && !input.force)
+        throw new Error(`${id} is claimed by ${held.by}; only that owner can release it (or use --force).`);
+    await writeFile(taskFile, withClaim(source, null, localDate(now)), "utf8");
+    return { released: true, id, was: held.by };
+}
+//# sourceMappingURL=claim-task.js.map

package/node_modules/@ocean/loop/dist/tasks/list-tasks.js

@@ -0,0 +1,113 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { parseTaskId, taskIdSpellings, } from "@ocean/core/domain/tasks/task-id.js";
+import { oceanPath, PROJECTS_DIR, projectSubdir, resolveWithin, WORKSPACE_PROJECT_ID, } from "@ocean/core/shared/paths.js";
+import { folderProject, projectsWithTasks, } from "@ocean/core/shared/project-resolution.js";
+/**
+ * Read task summaries for a project from the workspace. Lives in the application
+ * layer so both the CLI (`ocean tasks list`) and the MCP server can call it
+ * without the MCP server reaching back into the CLI layer.
+ */
+export async function listTasks(state, projectId = WORKSPACE_PROJECT_ID) {
+    const root = resolveWithin(oceanPath(PROJECTS_DIR), projectSubdir(oceanPath(PROJECTS_DIR), projectId), "tasks");
+    const records = [];
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return records;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === "archive")
+            continue;
+        const file = path.join(root, entry.name, "task.md");
+        let source;
+        try {
+            source = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const fields = Object.fromEntries(source
+            .slice(0, source.indexOf("\n---", 4))
+            .split("\n")
+            .slice(1)
+            .filter((line) => /^[\w-]+:/.test(line))
+            .map((line) => {
+            const index = line.indexOf(":");
+            const value = line.slice(index + 1).trim();
+            return [line.slice(0, index), value.replace(/^(["'])(.*)\1$/, "$2")];
+        }));
+        if (state && fields.state !== state)
+            continue;
+        const objective = source.match(/\n## Objective\n\n([\s\S]*?)(?=\n## |$)/)?.[1]?.trim() ??
+            "";
+        records.push({
+            id: fields.id ?? entry.name,
+            title: fields.title ?? "",
+            state: fields.state ?? "",
+            goal: objective || fields.goal || fields.requirement || "",
+            updatedAt: fields.updated ?? fields.updated_at ?? "",
+        });
+    }
+    return records.sort((a, b) => a.id.localeCompare(b.id));
+}
+// Projects whose live tasks/ holds this id (T-3 and T-003 are one task). Ids are unique per
+// project, not across projects.
+export async function projectsHoldingTask(id) {
+    if (!parseTaskId(id))
+        return [];
+    const holders = [];
+    for (const project of await projectsWithTasks()) {
+        for (const spelling of taskIdSpellings(id)) {
+            try {
+                await readFile(path.join(oceanPath(PROJECTS_DIR), projectSubdir(oceanPath(PROJECTS_DIR), project), "tasks", spelling, "task.md"), "utf8");
+                holders.push(project);
+                break;
+            }
+            catch {
+                /* not here */
+            }
+        }
+    }
+    return holders;
+}
+// "What tasks do I have" from a folder (T-256): --project wins; else the folder's project when
+// it has matching tasks; else every project's, labelled, with a note saying why.
+export async function listTasksForFolder(options) {
+    const { state } = options;
+    const label = (project, tasks) => tasks.map((task) => ({ ...task, project }));
+    if (options.project) {
+        // A mistyped id would otherwise read as a project with no tasks.
+        // resolveWithin throws on its own for an id that escapes the projects root.
+        const folder = resolveWithin(oceanPath(PROJECTS_DIR), projectSubdir(oceanPath(PROJECTS_DIR), options.project));
+        const isProject = await stat(folder).then((entry) => entry.isDirectory(), () => false);
+        if (!isProject)
+            throw new Error(`No project ${options.project} in ${PROJECTS_DIR}`);
+        return {
+            scope: "project",
+            project: options.project,
+            tasks: label(options.project, await listTasks(state, options.project)),
+        };
+    }
+    const project = await folderProject(options.cwd);
+    if (project) {
+        const own = await listTasks(state, project);
+        if (own.length)
+            return { scope: "project", project, tasks: label(project, own) };
+    }
+    const tasks = [];
+    for (const each of await projectsWithTasks())
+        tasks.push(...label(each, await listTasks(state, each)));
+    const which = state ? `${state} ` : "";
+    return {
+        scope: "all",
+        project,
+        tasks,
+        note: project
+            ? `No ${which}tasks in ${project}; showing every project.`
+            : `This folder is not an Ocean project; showing every project's ${which}tasks.`,
+    };
+}
+//# sourceMappingURL=list-tasks.js.map

package/node_modules/@ocean/loop/dist/tasks/new-task.js

@@ -0,0 +1,42 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { localDate } from "@ocean/core/shared/local-date.js";
+import { oceanPath, PROJECTS_DIR, projectSubdir, resolveWithin, } from "@ocean/core/shared/paths.js";
+import { withNextTaskId } from "@ocean/core/shared/project-resolution.js";
+// A new record in the shape `tasks doctor` validates and `tasks complete` can close: the
+// definition of done is a checkbox, so it can be ticked rather than rewritten first.
+export function taskRecord(input) {
+    const { id, title, project, objective, today } = input;
+    return `---\nid: ${id}\ntitle: ${JSON.stringify(title)}\nstate: active\nproject: ${project}\nopened: ${today}\nupdated: ${today}\nartifacts: []\nclass: medium\nexpected_context: medium\n---\n\n## Objective\n\n${objective}\n\n## Definition of done\n\n- [ ] The requested outcome is implemented and its verification passes.\n\n## Next action\n\nInspect the project and define the first implementation slice.\n\n## Verification\n\nPending.\n\n## Blockers\n\nNone.\n\n## Log\n\n- ${today} — Task created.\n`;
+}
+export function validTaskTitle(title) {
+    const trimmed = title?.trim();
+    return Boolean(trimmed && trimmed.length <= 200 && !/[\r\n]/.test(trimmed));
+}
+// `ocean tasks new`: the next free id comes from the projects lock (the highest id on disk,
+// live or archived, and the manifest counter), never from a hand-kept number.
+export async function newTask(projectId, title) {
+    if (!validTaskTitle(title))
+        throw new Error("A task needs a single-line title of at most 200 characters");
+    // A mistyped project would otherwise get a fresh folder and an id from the shared namespace.
+    const folder = resolveWithin(oceanPath(PROJECTS_DIR), projectSubdir(oceanPath(PROJECTS_DIR), projectId));
+    const isProject = await stat(folder).then((entry) => entry.isDirectory(), () => false);
+    if (!isProject)
+        throw new Error(`No project ${projectId} in ${PROJECTS_DIR}`);
+    const today = localDate();
+    const result = await withNextTaskId(projectId, async (id) => {
+        const file = resolveWithin(oceanPath(PROJECTS_DIR), projectSubdir(oceanPath(PROJECTS_DIR), projectId), "tasks", id, "task.md");
+        await mkdir(path.dirname(file), { recursive: true });
+        // `wx`: an id that already has a record is never overwritten.
+        await writeFile(file, taskRecord({
+            id,
+            title: title.trim(),
+            project: projectId,
+            objective: title.trim(),
+            today,
+        }), { flag: "wx" });
+        return { ok: true, id, file };
+    });
+    return { id: result.id, file: result.file };
+}
+//# sourceMappingURL=new-task.js.map

package/node_modules/@ocean/loop/dist/tasks/renumber-tasks.js

@@ -0,0 +1,134 @@
+import { access, readFile, rename } from "node:fs/promises";
+import path from "node:path";
+import { formatTaskId, isValidPrefix, LEGACY_PREFIX, parseTaskId, } from "@ocean/core/domain/tasks/task-id.js";
+import { atomicWrite } from "@ocean/core/shared/fs-utils.js";
+import { isWorkspaceProject, oceanRoot, PROJECTS_DIR, WORKSPACE_PROJECT_ID, } from "@ocean/core/shared/paths.js";
+import { highestTaskNumber, listProjectManifests, withProjectsLock, writeManifest, } from "@ocean/core/shared/project-resolution.js";
+import { taskFolders } from "@ocean/core/shared/task-reference.js";
+// Moves a project's tasks from the shared T namespace to its own prefix (T-256): T-300 becomes
+// OL-001, and the record keeps `legacyId: T-300` so every old reference still resolves. Dry run
+// unless `write`. Idempotent: a task already under the prefix keeps its number, so a rerun only
+// picks up what is new.
+export async function renumberTasks(options) {
+    const { project, prefix } = options;
+    if (isWorkspaceProject(project))
+        throw new Error(`${project} is the workspace project and keeps the ${LEGACY_PREFIX} namespace`);
+    if (prefix === LEGACY_PREFIX || !isValidPrefix(prefix))
+        throw new Error(`'${prefix}' is not a usable prefix: 1-6 upper-case letters or digits, starting with a letter, and not a reserved word`);
+    return withProjectsLock(async () => {
+        const manifests = await listProjectManifests();
+        const ocean = manifests.find((manifest) => manifest.id === WORKSPACE_PROJECT_ID);
+        if (!ocean)
+            throw new Error("no project.json for the workspace project; run `ocean project migrate --write` first");
+        const manifest = manifests.find((candidate) => candidate.id === project);
+        if (!manifest)
+            throw new Error(`no project.json for '${project}'; bind it before renumbering`);
+        const claimant = manifests.find((candidate) => candidate.prefix === prefix && candidate.id !== project);
+        if (claimant)
+            throw new Error(`prefix ${prefix} is already used by ${claimant.id}`);
+        if (manifest.prefix && manifest.prefix !== prefix)
+            throw new Error(`${project} already uses prefix ${manifest.prefix}`);
+        const projectsDir = path.join(oceanRoot(), PROJECTS_DIR);
+        const entries = [];
+        for (const [folder, file, archived] of await taskFolders(projectsDir, project)) {
+            let source;
+            try {
+                source = await readFile(file, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const head = source.slice(0, Math.max(source.indexOf("\n---", 4), 0));
+            const field = (name) => head.match(new RegExp(`^${name}:\\s*(.+)$`, "m"))?.[1]?.trim();
+            const declared = parseTaskId(field("id") ?? "");
+            const oldId = field("legacyId") ?? folder;
+            if (!parseTaskId(oldId))
+                continue;
+            entries.push({
+                folder,
+                file,
+                archived,
+                oldId,
+                declared: declared?.prefix === prefix ? declared.number : null,
+                source,
+            });
+        }
+        // Tasks already under the prefix keep their number; the rest are numbered after them, in
+        // the order of their old ids.
+        const kept = entries.filter((entry) => entry.declared !== null);
+        let counter = Math.max(0, ...kept.map((entry) => entry.declared ?? 0));
+        const pending = entries
+            .filter((entry) => entry.declared === null)
+            .sort((a, b) => (parseTaskId(a.oldId)?.number ?? 0) -
+            (parseTaskId(b.oldId)?.number ?? 0));
+        const targets = new Map();
+        for (const entry of kept)
+            targets.set(entry, formatTaskId(prefix, entry.declared));
+        for (const entry of pending) {
+            counter += 1;
+            targets.set(entry, formatTaskId(prefix, counter));
+        }
+        const moves = [];
+        for (const entry of entries) {
+            const to = targets.get(entry);
+            if (to === entry.folder && entry.declared !== null)
+                continue;
+            moves.push({ ...entry, to });
+        }
+        moves.sort((a, b) => a.to.localeCompare(b.to));
+        for (const move of moves) {
+            const destination = path.join(path.dirname(path.dirname(move.file)), move.to);
+            if (move.to !== move.folder && (await exists(destination)))
+                throw new Error(`${path.relative(oceanRoot(), destination)} already exists; resolve it before renumbering`);
+        }
+        const nextTask = Math.max(manifest.nextTask ?? 1, counter + 1);
+        const result = {
+            dryRun: !options.write,
+            project,
+            prefix,
+            moves: moves.map(({ folder, to, archived }) => ({
+                from: folder,
+                to,
+                archived,
+            })),
+            nextTask,
+        };
+        if (!options.write)
+            return result;
+        // Every record is rewritten in memory first, so one without an id in its frontmatter
+        // refuses the run before anything is written. Only the frontmatter changes.
+        const rewritten = moves.map((move) => {
+            const end = move.source.indexOf("\n---", 4);
+            if (!move.source.startsWith("---\n") ||
+                end < 0 ||
+                !/^id:/m.test(move.source.slice(0, end)))
+                throw new Error(`${path.relative(oceanRoot(), move.file)} has no id in its frontmatter`);
+            let head = move.source
+                .slice(0, end)
+                .replace(/^id:.*$/m, `id: ${move.to}`);
+            if (!/^legacyId:/m.test(head))
+                head = head.replace(/^id:.*$/m, (line) => `${line}\nlegacyId: ${move.oldId}`);
+            return { move, source: head + move.source.slice(end) };
+        });
+        // The T counter first: once these tasks leave the shared namespace the scan no longer sees
+        // their numbers, and no project on T may reissue them.
+        const globalMax = await highestTaskNumber(LEGACY_PREFIX);
+        await writeManifest({
+            ...ocean,
+            nextTask: Math.max(ocean.nextTask ?? 1, globalMax + 1),
+        });
+        // The prefix next, before any move: if a move fails, the ids already moved still resolve,
+        // and a rerun finishes the rest.
+        await writeManifest({ ...manifest, prefix, nextTask });
+        for (const { move, source } of rewritten) {
+            await atomicWrite(move.file, source);
+            if (move.to !== move.folder)
+                await rename(path.dirname(move.file), path.join(path.dirname(path.dirname(move.file)), move.to));
+        }
+        return result;
+    });
+}
+async function exists(target) {
+    return access(target).then(() => true, () => false);
+}
+//# sourceMappingURL=renumber-tasks.js.map

package/node_modules/@ocean/loop/dist/tasks/verification-readiness.js

@@ -0,0 +1,78 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { isWorkspaceProject, projectOfTasksRoot, repoRoot, resolveWithin, workspaceTasksRoot, } from "@ocean/core/shared/paths.js";
+import { expandHome, projectVerify, readProjectManifest, } from "@ocean/core/shared/project-resolution.js";
+import { declaredVerificationCommands } from "./verify-task.js";
+// Whether `ocean tasks complete` will be able to verify this task, checked early and without
+// running anything (T-291): T-283 named a test file that did not exist, which surfaced only at
+// completion. Advisory: a checkpoint reports it and never refuses.
+export async function verificationReadiness(id, root = workspaceTasksRoot()) {
+    const source = await readFile(resolveWithin(root, id, "task.md"), "utf8");
+    const { declared, refused } = declaredVerificationCommands(source);
+    const warnings = refused.map((command) => `declared verification is not allowed to run: ${command}`);
+    const project = projectOfTasksRoot(root);
+    const manifest = project
+        ? await readProjectManifest(project).catch(() => null)
+        : null;
+    const runnable = declared.filter((command) => !refused.includes(command));
+    if (!declared.length && !(manifest && projectVerify(manifest).length))
+        warnings.push("no verification command declared and no project verify: tasks complete will refuse");
+    // Task commands run in the engine for the workspace project, else in the project's first path.
+    const cwd = project && !isWorkspaceProject(project) && manifest?.paths?.[0]
+        ? expandHome(manifest.paths[0])
+        : repoRoot();
+    for (const command of runnable)
+        for (const file of missingTestFiles(command, cwd))
+            warnings.push(`test file not found: ${file} (in ${command})`);
+    return { ready: warnings.length === 0, warnings };
+}
+// Test files named after `node --test` that do not exist where the command will run. A
+// `pnpm --filter <name> exec` prefix runs inside that workspace package.
+function missingTestFiles(command, cwd) {
+    const missing = [];
+    for (const link of command.split(/\s*(?:&&|;)\s*/)) {
+        const tokens = link.trim().split(/\s+/);
+        const test = tokens.indexOf("--test");
+        if (test < 0 || !tokens.slice(0, test).includes("node"))
+            continue;
+        // `--filter <name>` or `--filter=<name>`.
+        const filter = tokens.findIndex((token) => token === "--filter" || token.startsWith("--filter="));
+        const name = filter < 0
+            ? undefined
+            : tokens[filter].includes("=")
+                ? tokens[filter].slice("--filter=".length)
+                : tokens[filter + 1];
+        const base = tokens[0] === "pnpm" && filter >= 0 ? packageDirectory(cwd, name) : cwd;
+        if (!base)
+            continue;
+        for (const arg of tokens.slice(test + 1))
+            if (!arg.startsWith("-") && /\.(?:[cm]?js|ts)$/.test(arg))
+                if (!existsSync(path.resolve(base, arg)))
+                    missing.push(arg);
+    }
+    return missing;
+}
+function packageDirectory(cwd, name) {
+    if (!name)
+        return null;
+    const packages = path.join(cwd, "packages");
+    let entries;
+    try {
+        entries = readdirSync(packages);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries)
+        try {
+            const manifest = JSON.parse(readFileSync(path.join(packages, entry, "package.json"), "utf8"));
+            if (manifest.name === name)
+                return path.join(packages, entry);
+        }
+        catch {
+            // not a package
+        }
+    return null;
+}
+//# sourceMappingURL=verification-readiness.js.map