scribeclock 0.0.0-stage → 0.1.1

package/dist/commands/projects.js

@@ -0,0 +1,354 @@
+import { readFileSync } from "node:fs";
+import { usageError } from "../cli/errors.js";
+import { diffLines, fmtDate, parseWhen } from "../util/format.js";
+import { PROJECT_FLAG, bool, cmd, emit, num, personName, projectArg, requirePositional, resolveProjectId, str } from "./_shared.js";
+export const projectsList = cmd({
+    path: "projects list",
+    group: "Projects & PRDs",
+    summary: "Projects with status, progress, repositories and open-task counts.",
+    tool: "list_projects",
+    positionals: [{ name: "query", description: "Name/description filter." }],
+    flags: [
+        { name: "status", alias: "s", type: "string", choices: ["pipeline", "planning", "active", "on_hold", "completed", "archived"], description: "Only this status." },
+        { name: "limit", alias: "n", type: "number", description: "Max projects (default 100)." },
+    ],
+    async run(ctx, inv) {
+        const data = await ctx.call("list_projects", { query: inv.positionals.join(" ") || undefined, status: str(inv.flags.status), limit: num(inv.flags.limit) });
+        return emit(ctx, data, () => {
+            const projects = (data.projects ?? []);
+            ctx.out.table(["name", "status", "progress", "open", "urgency", "repos", "organization"], projects.map((p) => [p.name, p.status, `${String(p.progress_percent ?? 0)}%`, p.open_task_count, p.urgency, p.github_repos?.join(", ") ?? "", p.organization?.name]));
+            ctx.out.info(ctx.out.dim(`${projects.length} project${projects.length === 1 ? "" : "s"}`));
+        });
+    },
+});
+export const projectsShow = cmd({
+    path: "projects show",
+    group: "Projects & PRDs",
+    summary: "Project detail: assignees, task counts, PRD versions, Drive, design links.",
+    tool: "get_project",
+    positionals: [{ name: "project", description: "Project uuid or exact name (default from .scribeclock.json)." }],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true, positional: 0 });
+        const data = await ctx.call("get_project", { project_id });
+        return emit(ctx, data, () => {
+            const p = (data.project ?? data);
+            ctx.out.log(ctx.out.bold(String(p.name ?? "")));
+            ctx.out.kv([
+                ["status", p.status],
+                ["urgency", p.urgency],
+                ["progress", `${String(p.progress_percent ?? 0)}%${p.progress_manual_override ? " (manual)" : ""}`],
+                ["deadline", p.target_deadline ? fmtDate(String(p.target_deadline)) : ""],
+                ["repos", p.github_repos?.join(", ")],
+                ["website", p.website_url],
+                ["organization", p.organization?.name],
+                ["tasks", p.task_counts ? JSON.stringify(p.task_counts) : p.open_task_count !== undefined ? `${String(p.open_task_count)} open` : ""],
+                ["PRD versions", p.prd_version_count ?? (Array.isArray(p.prd_versions) ? p.prd_versions.length : "")],
+                ["Google Drive", p.has_google_drive ? "linked" : "not linked"],
+                ["url", p.url],
+            ]);
+            if (typeof p.description === "string" && p.description) {
+                ctx.out.log("");
+                ctx.out.log(`  ${p.description.replace(/<[^>]+>/g, "").trim()}`);
+            }
+            const assignees = (p.assignees ?? data.assignees ?? []);
+            if (assignees.length) {
+                ctx.out.log("");
+                ctx.out.log(ctx.out.bold("Assignees"));
+                for (const a of assignees)
+                    ctx.out.log(`  ${personName(a.person ?? a)}${a.role ? ctx.out.dim(` · ${String(a.role)}`) : ""}`);
+            }
+            const links = (p.design_links ?? []);
+            if (links.length) {
+                ctx.out.log("");
+                ctx.out.log(ctx.out.bold("Design links"));
+                for (const l of links)
+                    ctx.out.log(`  ${String(l.provider ?? l.kind ?? "")} ${String(l.url ?? "")}`);
+            }
+        });
+    },
+});
+export const projectsCreate = cmd({
+    path: "projects create",
+    group: "Projects & PRDs",
+    summary: "Create a project (admins/staff).",
+    tool: "create_project",
+    positionals: [{ name: "name", required: true, description: "Project name." }],
+    flags: [
+        { name: "description", alias: "d", type: "string", description: "Description." },
+        { name: "status", alias: "s", type: "string", choices: ["pipeline", "planning", "active", "on_hold", "completed", "archived"], description: "Initial status (default pipeline)." },
+        { name: "urgency", type: "string", choices: ["low", "normal", "high", "urgent"], description: "Urgency." },
+        { name: "deadline", type: "string", placeholder: "<YYYY-MM-DD>", description: "Target deadline." },
+        { name: "repo", type: "string", placeholder: "<owner/repo>", description: "Primary GitHub repository." },
+        { name: "website", type: "string", description: "Website URL." },
+    ],
+    async run(ctx, inv) {
+        const name = requirePositional(inv, 0, "A project name", 'scribeclock projects create "Kisa Print"');
+        const data = await ctx.call("create_project", { name, description: str(inv.flags.description), status: str(inv.flags.status), urgency: str(inv.flags.urgency), target_deadline: str(inv.flags.deadline), github_repo_full_name: str(inv.flags.repo), website_url: str(inv.flags.website) });
+        return emit(ctx, data, () => {
+            const p = (data.project ?? data);
+            ctx.out.log(`${ctx.out.green("✓")} Created project ${ctx.out.bold(String(p.name ?? name))}${p.url ? ctx.out.dim(`  ${String(p.url)}`) : ""}`);
+        });
+    },
+});
+export const projectsUpdate = cmd({
+    path: "projects update",
+    group: "Projects & PRDs",
+    summary: "Change status, progress, urgency, deadline, description, repo, website or design links.",
+    tool: "update_project",
+    positionals: [{ name: "project", description: "Project uuid or exact name (default from .scribeclock.json)." }],
+    flags: [
+        { name: "name", type: "string", description: "Rename." },
+        { name: "description", alias: "d", type: "string", description: "New description (@file reads a file)." },
+        { name: "status", alias: "s", type: "string", choices: ["pipeline", "planning", "active", "on_hold", "completed", "archived"], description: "New status." },
+        { name: "urgency", type: "string", choices: ["low", "normal", "high", "urgent"], description: "Urgency." },
+        { name: "progress", type: "number", placeholder: "<0-100>", description: "Progress percent (sets a manual override)." },
+        { name: "deadline", type: "string", placeholder: "<YYYY-MM-DD|none>", description: "Target deadline; none clears." },
+        { name: "repo", type: "string", placeholder: "<owner/repo>", description: "GitHub repository." },
+        { name: "website", type: "string", description: "Website URL." },
+        { name: "add-design", type: "string", placeholder: "<url>", description: "Attach a Paper/Figma/Canva/Rive/Stitch link." },
+        { name: "remove-design", type: "string", placeholder: "<url>", description: "Remove a design link." },
+    ],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true, positional: 0 });
+        const description = typeof inv.flags.description === "string" ? (inv.flags.description.startsWith("@") ? readFileSync(inv.flags.description.slice(1), "utf8") : inv.flags.description) : undefined;
+        const args = {
+            project_id,
+            name: str(inv.flags.name),
+            description,
+            status: str(inv.flags.status),
+            urgency: str(inv.flags.urgency),
+            progress_percent: num(inv.flags.progress),
+            target_deadline: inv.flags.deadline === "none" ? null : str(inv.flags.deadline),
+            github_repo_full_name: str(inv.flags.repo),
+            website_url: str(inv.flags.website),
+            add_design_link: str(inv.flags["add-design"]),
+            remove_design_link: str(inv.flags["remove-design"]),
+        };
+        if (!Object.entries(args).some(([k, v]) => k !== "project_id" && v !== undefined))
+            throw usageError("Nothing to change.", "Pass --status, --progress, --deadline, --description…");
+        const data = await ctx.call("update_project", args);
+        return emit(ctx, data, () => ctx.out.log(`${ctx.out.green("✓")} Updated ${ctx.out.bold(String((data.project ?? data).name ?? project_id))}.`));
+    },
+});
+export const prdList = cmd({
+    path: "prd list",
+    group: "Projects & PRDs",
+    summary: "Versions / phases of a project's requirements document.",
+    tool: "list_prd_versions",
+    positionals: [{ name: "project", description: "Project uuid or name (default from .scribeclock.json)." }],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true, positional: 0 });
+        const data = await ctx.call("list_prd_versions", { project_id });
+        return emit(ctx, data, () => {
+            const versions = (data.versions ?? []);
+            if (!versions.length)
+                ctx.out.log(ctx.out.dim("No PRD versions yet. Create one: scribeclock prd create --project <p> --file prd.md"));
+            else
+                ctx.out.table(["version", "phase", "order", "complete", "baseline", "size", "updated"], versions.map((v) => [v.version_code, v.phase_label, v.sort_order, v.completed ? "yes" : "", v.is_production_milestone || v.is_locked_baseline ? "yes" : "", v.size_chars ?? v.size ?? v.markdown_chars, fmtDate(String(v.updated_at ?? v.created_at ?? ""))]));
+        });
+    },
+});
+async function fetchPrd(ctx, project_id, version) {
+    const args = /^[0-9a-f-]{36}$/i.test(version ?? "") ? { prd_version_id: version } : { project_id, version_code: version };
+    return ctx.call("get_prd_version", args);
+}
+function prdMarkdown(data) {
+    const v = (data.version ?? data);
+    return String(v.requirements_markdown ?? data.requirements_markdown ?? "");
+}
+export const prdShow = cmd({
+    path: "prd show",
+    group: "Projects & PRDs",
+    summary: "Print a PRD version as Markdown (latest by default): prd show [version] --project P.",
+    tool: "get_prd_version",
+    positionals: [{ name: "version", description: "Version code (v2, MVP) or version uuid. Default: latest." }],
+    flags: [PROJECT_FLAG],
+    examples: ["scribeclock prd show --project 'Scribe Clock' > prd.md", "scribeclock prd show v2 -p 'Scribe Clock'"],
+    async run(ctx, inv) {
+        const version = inv.positionals[0];
+        const project_id = projectArg(ctx, inv, { required: !/^[0-9a-f-]{36}$/i.test(version ?? "") });
+        const data = await fetchPrd(ctx, project_id, version);
+        return emit(ctx, data, () => {
+            const v = (data.version ?? data);
+            if (v.version_code)
+                ctx.out.info(ctx.out.dim(`${String(v.version_code)}${v.phase_label ? ` · ${String(v.phase_label)}` : ""}`));
+            ctx.out.log(prdMarkdown(data));
+        });
+    },
+});
+export const prdCreate = cmd({
+    path: "prd create",
+    group: "Projects & PRDs",
+    summary: "Add a PRD version from a Markdown file: prd create --project P --file prd.md.",
+    tool: "create_prd_version",
+    flags: [
+        PROJECT_FLAG,
+        { name: "file", alias: "f", type: "string", placeholder: "<path>", description: "Markdown file (- for stdin).", required: true },
+        { name: "version", alias: "v", type: "string", description: "Version code (default next vN)." },
+        { name: "phase", type: "string", description: "Phase label." },
+        { name: "order", type: "number", description: "Sort order." },
+        { name: "milestone", type: "boolean", description: "Mark as production milestone." },
+    ],
+    async run(ctx, inv) {
+        const project_id = projectArg(ctx, inv, { required: true });
+        const file = String(inv.flags.file);
+        const requirements_markdown = file === "-" ? readFileSync(0, "utf8") : readFileSync(file, "utf8");
+        const data = await ctx.call("create_prd_version", { project_id, requirements_markdown, version_code: str(inv.flags.version), phase_label: str(inv.flags.phase), sort_order: num(inv.flags.order), is_production_milestone: bool(inv.flags.milestone) });
+        return emit(ctx, data, () => {
+            const v = (data.version ?? data);
+            ctx.out.log(`${ctx.out.green("✓")} Created PRD ${ctx.out.bold(String(v.version_code ?? ""))} (${requirements_markdown.length} chars).`);
+        });
+    },
+});
+export const prdUpdate = cmd({
+    path: "prd update",
+    group: "Projects & PRDs",
+    summary: "Replace or append to a PRD version, or change its label / order / completion.",
+    tool: "update_prd_version",
+    positionals: [{ name: "version", description: "Version code or uuid (default: latest when --project is given… pass it explicitly to be safe)." }],
+    flags: [
+        PROJECT_FLAG,
+        { name: "file", alias: "f", type: "string", placeholder: "<path>", description: "Markdown file with the new content (- for stdin)." },
+        { name: "append", type: "boolean", description: "Append instead of replacing the Markdown." },
+        { name: "phase", type: "string", description: "Phase label." },
+        { name: "order", type: "number", description: "Sort order." },
+        { name: "complete", type: "boolean", description: "Mark complete (--no-complete reopens)." },
+        { name: "milestone", type: "boolean", description: "Production milestone flag." },
+    ],
+    async run(ctx, inv) {
+        const version = inv.positionals[0];
+        if (!version)
+            throw usageError("Which version? Pass its code (v2) or uuid.", "scribeclock prd list --project <p>");
+        const project_id = projectArg(ctx, inv, { required: !/^[0-9a-f-]{36}$/i.test(version) });
+        const file = str(inv.flags.file);
+        const requirements_markdown = file ? (file === "-" ? readFileSync(0, "utf8") : readFileSync(file, "utf8")) : undefined;
+        const args = /^[0-9a-f-]{36}$/i.test(version) ? { prd_version_id: version } : { project_id, version_code: version };
+        Object.assign(args, { requirements_markdown, mode: inv.flags.append ? "append" : undefined, phase_label: str(inv.flags.phase), sort_order: num(inv.flags.order), completed: bool(inv.flags.complete), is_production_milestone: bool(inv.flags.milestone) });
+        const data = await ctx.call("update_prd_version", args);
+        return emit(ctx, data, () => ctx.out.log(`${ctx.out.green("✓")} Updated PRD ${version}.`));
+    },
+});
+export const prdDiff = cmd({
+    path: "prd diff",
+    group: "Projects & PRDs",
+    summary: "Line diff between two PRD versions: prd diff v1 v2 --project P.",
+    tool: "get_prd_version",
+    positionals: [{ name: "from", required: true, description: "Older version code or uuid." }, { name: "to", required: true, description: "Newer version code or uuid." }],
+    flags: [PROJECT_FLAG, { name: "context", alias: "c", type: "number", description: "Unchanged lines to show around changes (default 2; -1 for all)." }],
+    examples: ["scribeclock prd diff v1 v2 --project 'Scribe Clock'"],
+    async run(ctx, inv) {
+        const [from, to] = [requirePositional(inv, 0, "The older version", "scribeclock prd diff v1 v2 -p <project>"), requirePositional(inv, 1, "The newer version", "scribeclock prd diff v1 v2 -p <project>")];
+        const project_id = projectArg(ctx, inv, { required: !(/^[0-9a-f-]{36}$/i.test(from) && /^[0-9a-f-]{36}$/i.test(to)) });
+        const [a, b] = await Promise.all([fetchPrd(ctx, project_id, from), fetchPrd(ctx, project_id, to)]);
+        const diff = diffLines(prdMarkdown(a).split("\n"), prdMarkdown(b).split("\n"));
+        const added = diff.filter((d) => d.op === "+").length;
+        const removed = diff.filter((d) => d.op === "-").length;
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ok: true, from, to, added, removed, hunks: diff.filter((d) => d.op !== " ").map((d) => ({ op: d.op, text: d.text })), lines: diff });
+            return 0;
+        }
+        const context = inv.flags.context === undefined ? 2 : Number(inv.flags.context);
+        ctx.out.log(ctx.out.bold(`--- ${from}    +++ ${to}    ${ctx.out.green(`+${added}`)} ${ctx.out.red(`-${removed}`)}`));
+        const keep = new Set();
+        diff.forEach((d, i) => {
+            if (d.op !== " ")
+                for (let j = Math.max(0, i - context); j <= Math.min(diff.length - 1, i + context); j++)
+                    keep.add(j);
+        });
+        let lastShown = -1;
+        diff.forEach((d, i) => {
+            if (context >= 0 && !keep.has(i))
+                return;
+            if (lastShown >= 0 && i > lastShown + 1)
+                ctx.out.log(ctx.out.dim("  …"));
+            lastShown = i;
+            const line = `${d.op} ${d.text}`;
+            ctx.out.log(d.op === "+" ? ctx.out.green(line) : d.op === "-" ? ctx.out.red(line) : ctx.out.dim(line));
+        });
+        return 0;
+    },
+});
+/** Headings, task-list items and "As a … I want …" stories → draft tasks. */
+export function prdToDraftTasks(markdown) {
+    const drafts = [];
+    let section = "";
+    const lines = markdown.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const h = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (h) {
+            section = h[2].trim();
+            continue;
+        }
+        const task = /^\s*[-*]\s+\[[ xX]?\]\s+(.*)$/.exec(line);
+        const story = /^\s*(?:[-*]\s+)?(As an? .+?,? I (?:want|need|can) .+)$/i.exec(line);
+        const req = /^\s*(?:[-*]|\d+\.)\s+((?:The (?:system|app|user|admin)|Users?|Admins?|Must|Should|Shall)\b.*)$/i.exec(line);
+        const text = task?.[1] ?? story?.[1] ?? req?.[1];
+        if (!text)
+            continue;
+        const title = text.replace(/\*\*/g, "").trim().slice(0, 140);
+        if (title.length < 6)
+            continue;
+        // Collect indented continuation lines as the description.
+        const detail = [];
+        for (let j = i + 1; j < lines.length && /^\s{2,}\S/.test(lines[j]); j++)
+            detail.push(lines[j].trim());
+        drafts.push({ title, description: [section ? `From PRD section: ${section}` : "", ...detail].filter(Boolean).join("\n"), section });
+    }
+    return drafts;
+}
+export const prdToTasks = cmd({
+    path: "prd to-tasks",
+    group: "Projects & PRDs",
+    summary: "Break a PRD version into draft tasks (checklist items, user stories, requirements) and create them after review.",
+    tool: ["get_prd_version", "create_task"],
+    positionals: [{ name: "version", description: "Version code or uuid (default latest)." }],
+    flags: [
+        PROJECT_FLAG,
+        { name: "create", type: "boolean", description: "Create the tasks (otherwise only the drafts are printed)." },
+        { name: "priority", type: "string", choices: ["low", "medium", "high"], description: "Priority for created tasks." },
+        { name: "assignee", alias: "a", type: "string", description: "Assignee for created tasks." },
+        { name: "limit", alias: "n", type: "number", description: "Max drafts (default 50)." },
+    ],
+    examples: ["scribeclock prd to-tasks --project 'Scribe Clock'", "scribeclock prd to-tasks v2 -p 'Scribe Clock' --create --yes"],
+    async run(ctx, inv) {
+        const version = inv.positionals[0];
+        const project_id = projectArg(ctx, inv, { required: !/^[0-9a-f-]{36}$/i.test(version ?? "") });
+        const data = await fetchPrd(ctx, project_id, version);
+        const drafts = prdToDraftTasks(prdMarkdown(data)).slice(0, num(inv.flags.limit) ?? 50);
+        if (!inv.flags.create) {
+            return emit(ctx, { ok: true, count: drafts.length, drafts }, () => {
+                if (!drafts.length)
+                    ctx.out.log(ctx.out.dim("No checklist items, user stories or requirement lines found."));
+                else
+                    ctx.out.table(["#", "title", "section"], drafts.map((d, i) => [i + 1, d.title, d.section]));
+                ctx.out.info(ctx.out.dim(`${drafts.length} drafts. Add --create to file them as tasks.`));
+            });
+        }
+        if (!drafts.length)
+            throw usageError("Nothing to create.");
+        const { confirm } = await import("../cli/confirm.js");
+        if (!ctx.flags.dryRun) {
+            const ok = await confirm(ctx, `Create ${drafts.length} tasks in project ${project_id ?? "(from version)"}?`);
+            if (!ok)
+                return 1;
+        }
+        const created = [];
+        for (const d of drafts) {
+            if (ctx.flags.dryRun) {
+                ctx.out.log(`${ctx.out.dim("dry run →")} create_task ${JSON.stringify({ title: d.title, project_id })}`);
+                continue;
+            }
+            const r = await ctx.call("create_task", { title: d.title, description: d.description || undefined, project_id: await resolveProjectId(ctx, typeof project_id === "string" ? project_id : undefined), priority: str(inv.flags.priority), assignee: str(inv.flags.assignee) });
+            created.push((r.task ?? r));
+            ctx.out.info(`${ctx.out.green("✓")} ${String((r.task ?? r).key ?? "")} ${d.title}`);
+        }
+        if (ctx.flags.json)
+            ctx.out.jsonOut({ ok: true, created: created.length, tasks: created });
+        else if (!ctx.flags.dryRun)
+            ctx.out.log(`Created ${created.length} tasks.`);
+        return 0;
+    },
+});
+export const PROJECT_COMMANDS = [projectsList, projectsShow, projectsCreate, projectsUpdate, prdList, prdShow, prdCreate, prdUpdate, prdDiff, prdToTasks];
+void parseWhen;