codecartographer-pi 0.1.0 → 0.1.2

package/dist/core/utils.js

@@ -0,0 +1,46 @@
+// General-purpose helpers used by yaml/status/prompts and by wrapper-specific
+// path-boundary enforcement (Pi tool interception, MCP cwd validation).
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { normalize, resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+export function sleep(ms) {
+    return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+export async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function canonicalPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+export function normalizeForComparison(path) {
+    const normalized = normalize(path);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+export function isWithinPath(path, root) {
+    const normalizedPath = normalizeForComparison(resolve(path));
+    const normalizedRoot = normalizeForComparison(resolve(root));
+    if (normalizedPath === normalizedRoot)
+        return true;
+    return normalizedPath.startsWith(`${normalizedRoot}${process.platform === "win32" ? "\\" : "/"}`);
+}
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function uniqueStrings(items) {
+    return [...new Set(items.filter(Boolean))];
+}
+export function dateOnly(timestamp) {
+    return timestamp.slice(0, 10);
+}

package/dist/core/workspace.d.ts

@@ -0,0 +1,10 @@
+import type { WorkspaceState } from "./types.ts";
+export declare const packagedWorkspaceDir: string;
+export declare function getWorkspaceState(cwd: string): Promise<WorkspaceState | null>;
+export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<{
+    state: WorkspaceState;
+    threadLogEntry?: string;
+}> | {
+    state: WorkspaceState;
+    threadLogEntry?: string;
+}): Promise<WorkspaceState>;

package/dist/core/workspace.js

@@ -0,0 +1,83 @@
+// Workspace bootstrap: resolves the packaged .codecarto/ template directory
+// (so the MCP server and Pi can both copy from it on /codecarto-init), loads
+// + normalizes the per-project workspace state from disk, and provides the
+// atomic status-update primitive used by /codecarto-complete.
+import { existsSync } from "node:fs";
+import { appendFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { acquireLock, normalizeStatus } from "./status.js";
+import { pathExists } from "./utils.js";
+import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
+// Walk up from the current file to find the package root. Needed because the
+// source lives at <root>/core/workspace.ts (one level below the package root)
+// but compiles to <root>/dist/core/workspace.js (two levels below). A fixed
+// `..` only works in one of those layouts, so resolve `package.json` instead.
+function findPackageRoot(start) {
+    let dir = start;
+    while (true) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`Could not locate package.json starting from ${start}`);
+        }
+        dir = parent;
+    }
+}
+const coreDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = findPackageRoot(coreDir);
+// Path to the packaged framework template directory. Wrappers copy this on
+// /codecarto-init.
+export const packagedWorkspaceDir = join(packageRoot, ".codecarto");
+export async function getWorkspaceState(cwd) {
+    const workspaceDir = join(cwd, ".codecarto");
+    const statusPath = join(workspaceDir, "workflow", "status.yaml");
+    if (!(await pathExists(statusPath)))
+        return null;
+    const rawStatus = await loadYamlFile(statusPath);
+    const pipelineRelativePath = rawStatus.pipeline?.trim();
+    if (!pipelineRelativePath) {
+        throw new Error(`Missing pipeline in ${relative(cwd, statusPath) || statusPath}`);
+    }
+    const pipelinePath = join(workspaceDir, pipelineRelativePath);
+    if (!(await pathExists(pipelinePath))) {
+        throw new Error(`Active pipeline does not exist: ${relative(cwd, pipelinePath) || pipelinePath}`);
+    }
+    const pipeline = await loadYamlFile(pipelinePath);
+    const status = normalizeStatus(rawStatus, pipeline, pipelineRelativePath, cwd);
+    return {
+        cwd,
+        workspaceDir,
+        statusPath,
+        pipelinePath,
+        pipeline,
+        status,
+    };
+}
+export async function updateStatusAtomically(cwd, updater) {
+    const workspaceDir = join(cwd, ".codecarto");
+    const statusPath = join(workspaceDir, "workflow", "status.yaml");
+    const lockPath = `${statusPath}.lock`;
+    const lock = await acquireLock(lockPath);
+    try {
+        const currentState = await getWorkspaceState(cwd);
+        if (!currentState) {
+            throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
+        }
+        const result = await updater(currentState);
+        const nextState = result.state;
+        const serialized = `${stringifySimpleYaml(nextState.status)}\n`;
+        const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tempPath, serialized, "utf8");
+        await rename(tempPath, statusPath);
+        if (result.threadLogEntry) {
+            const threadLogPath = join(workspaceDir, "THREAD_LOG.md");
+            await appendFile(threadLogPath, result.threadLogEntry, "utf8");
+        }
+        return nextState;
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/core/yaml.d.ts

@@ -0,0 +1,6 @@
+export declare function stripYamlComment(value: string): string;
+export declare function parseYamlScalar(rawValue: string): unknown;
+export declare function parseSimpleYaml(raw: string): unknown;
+export declare function formatYamlScalar(value: unknown): string;
+export declare function stringifySimpleYaml(value: unknown, indent?: number): string;
+export declare function loadYamlFile<T>(path: string): Promise<T>;

package/dist/core/yaml.js

@@ -0,0 +1,259 @@
+// Hand-rolled YAML parser/serializer good enough for the .codecarto workflow
+// files (mappings, sequences, scalars, nested maps, strings/numbers/booleans).
+// Round-trips structured carry_forward/open_questions entries.
+import { readFile } from "node:fs/promises";
+import { isPlainObject } from "./utils.js";
+export function stripYamlComment(value) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        if (char === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (char === '"' && !inSingle && value[i - 1] !== "\\") {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (char === "#" && !inSingle && !inDouble) {
+            if (i === 0 || /\s/.test(value[i - 1] ?? "")) {
+                return value.slice(0, i).trimEnd();
+            }
+        }
+    }
+    return value.trimEnd();
+}
+function countIndent(line) {
+    let count = 0;
+    for (const char of line) {
+        if (char === " ")
+            count++;
+        else if (char === "\t")
+            count += 2;
+        else
+            break;
+    }
+    return count;
+}
+function isBlankOrComment(line) {
+    const trimmed = line.trim();
+    return trimmed === "" || trimmed.startsWith("#");
+}
+function findKeySeparator(text) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (char === '"' && !inSingle && text[i - 1] !== "\\") {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (char === ":" && !inSingle && !inDouble) {
+            return i;
+        }
+    }
+    return -1;
+}
+export function parseYamlScalar(rawValue) {
+    const trimmed = stripYamlComment(rawValue).trim();
+    if (trimmed === "")
+        return "";
+    if (trimmed === "[]")
+        return [];
+    if (trimmed === "{}")
+        return {};
+    if (trimmed === "null")
+        return null;
+    if (trimmed === "true")
+        return true;
+    if (trimmed === "false")
+        return false;
+    if (/^-?\d+$/.test(trimmed))
+        return Number.parseInt(trimmed, 10);
+    if (/^-?\d+\.\d+$/.test(trimmed))
+        return Number.parseFloat(trimmed);
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return trimmed.slice(1, -1);
+        }
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1).replace(/''/g, "'");
+    }
+    return trimmed;
+}
+export function parseSimpleYaml(raw) {
+    const lines = raw.split(/\r?\n/);
+    let index = 0;
+    const skipBlank = () => {
+        while (index < lines.length && isBlankOrComment(lines[index] ?? ""))
+            index++;
+    };
+    const parseBlock = (indent) => {
+        skipBlank();
+        if (index >= lines.length)
+            return {};
+        const line = lines[index] ?? "";
+        const lineIndent = countIndent(line);
+        const trimmed = line.slice(lineIndent);
+        if (trimmed.startsWith("- ") || trimmed === "-") {
+            return parseSequence(indent);
+        }
+        return parseMapping(indent);
+    };
+    const parseMapping = (indent) => {
+        const result = {};
+        while (index < lines.length) {
+            skipBlank();
+            if (index >= lines.length)
+                break;
+            const line = lines[index] ?? "";
+            const lineIndent = countIndent(line);
+            if (lineIndent < indent)
+                break;
+            if (lineIndent > indent) {
+                throw new Error(`Invalid YAML indentation near: ${line.trim()}`);
+            }
+            const trimmed = line.slice(indent);
+            if (trimmed.startsWith("- ") || trimmed === "-")
+                break;
+            const separator = findKeySeparator(trimmed);
+            if (separator === -1) {
+                throw new Error(`Invalid YAML mapping entry: ${trimmed}`);
+            }
+            const key = trimmed.slice(0, separator).trim();
+            const rawValue = trimmed.slice(separator + 1).trim();
+            index++;
+            if (rawValue !== "") {
+                result[key] = parseYamlScalar(rawValue);
+                continue;
+            }
+            skipBlank();
+            if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
+                result[key] = parseBlock(countIndent(lines[index] ?? ""));
+            }
+            else {
+                result[key] = null;
+            }
+        }
+        return result;
+    };
+    const parseSequence = (indent) => {
+        const result = [];
+        while (index < lines.length) {
+            skipBlank();
+            if (index >= lines.length)
+                break;
+            const line = lines[index] ?? "";
+            const lineIndent = countIndent(line);
+            if (lineIndent < indent)
+                break;
+            const trimmed = line.slice(lineIndent);
+            if (lineIndent !== indent || (!trimmed.startsWith("- ") && trimmed !== "-"))
+                break;
+            const rawItem = trimmed === "-" ? "" : trimmed.slice(2).trim();
+            index++;
+            if (rawItem === "") {
+                skipBlank();
+                if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
+                    result.push(parseBlock(countIndent(lines[index] ?? "")));
+                }
+                else {
+                    result.push(null);
+                }
+                continue;
+            }
+            const separator = findKeySeparator(rawItem);
+            if (separator !== -1) {
+                const key = rawItem.slice(0, separator).trim();
+                const rawValue = rawItem.slice(separator + 1).trim();
+                const item = {};
+                item[key] = rawValue === "" ? null : parseYamlScalar(rawValue);
+                skipBlank();
+                if (rawValue === "" && index < lines.length && countIndent(lines[index] ?? "") > indent + 1) {
+                    item[key] = parseBlock(countIndent(lines[index] ?? ""));
+                }
+                if (index < lines.length && countIndent(lines[index] ?? "") > indent) {
+                    const nested = parseMapping(indent + 2);
+                    for (const [nestedKey, nestedValue] of Object.entries(nested))
+                        item[nestedKey] = nestedValue;
+                }
+                result.push(item);
+                continue;
+            }
+            result.push(parseYamlScalar(rawItem));
+        }
+        return result;
+    };
+    skipBlank();
+    if (index >= lines.length)
+        return {};
+    return parseBlock(countIndent(lines[index] ?? ""));
+}
+export function formatYamlScalar(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value))
+        return value.length === 0 ? "[]" : JSON.stringify(value);
+    if (isPlainObject(value))
+        return Object.keys(value).length === 0 ? "{}" : JSON.stringify(value);
+    const stringValue = String(value);
+    if (stringValue === "")
+        return '""';
+    if (/^[A-Za-z0-9_./-]+$/.test(stringValue))
+        return stringValue;
+    return JSON.stringify(stringValue);
+}
+export function stringifySimpleYaml(value, indent = 0) {
+    const prefix = " ".repeat(indent);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return `${prefix}[]`;
+        return value
+            .map((item) => {
+            if (Array.isArray(item) || isPlainObject(item)) {
+                const isEmptyObject = isPlainObject(item) && Object.keys(item).length === 0;
+                if (Array.isArray(item) && item.length === 0)
+                    return `${prefix}- []`;
+                if (isEmptyObject)
+                    return `${prefix}- {}`;
+                return `${prefix}-\n${stringifySimpleYaml(item, indent + 2)}`;
+            }
+            return `${prefix}- ${formatYamlScalar(item)}`;
+        })
+            .join("\n");
+    }
+    if (isPlainObject(value)) {
+        const entries = Object.entries(value);
+        if (entries.length === 0)
+            return `${prefix}{}`;
+        return entries
+            .map(([key, entryValue]) => {
+            if (Array.isArray(entryValue) || isPlainObject(entryValue)) {
+                const isEmptyObject = isPlainObject(entryValue) && Object.keys(entryValue).length === 0;
+                if (Array.isArray(entryValue) && entryValue.length === 0)
+                    return `${prefix}${key}: []`;
+                if (isEmptyObject)
+                    return `${prefix}${key}: {}`;
+                return `${prefix}${key}:\n${stringifySimpleYaml(entryValue, indent + 2)}`;
+            }
+            return `${prefix}${key}: ${formatYamlScalar(entryValue)}`;
+        })
+            .join("\n");
+    }
+    return `${prefix}${formatYamlScalar(value)}`;
+}
+export async function loadYamlFile(path) {
+    const raw = await readFile(path, "utf8");
+    return (parseSimpleYaml(raw) ?? {});
+}

package/dist/extensions/codecarto/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function codeCartographerExtension(pi: ExtensionAPI): void;