@cmetech/otto 1.1.1 → 1.2.5

package/packages/coworker-artifacts/dist/artifact-store.js

@@ -0,0 +1,187 @@
+// packages/coworker-artifacts/src/artifact-store.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { join, normalize } from 'node:path';
+import { ARTIFACT_KINDS } from './types.js';
+import { ArtifactKindRejected, ArtifactNotFound, } from './errors.js';
+import { deriveSlug, nextCollisionSlug } from './slug.js';
+import { takeSnapshot, diffSnapshots } from './dir-snapshot.js';
+import { renderReadme } from './readme-renderer.js';
+const ARTIFACTS_DIR_NAME = '.otto/artifacts';
+const PRIMARY_FILE = 'report.md';
+export class ArtifactStore {
+    workspaceDir;
+    now;
+    constructor(opts) {
+        this.workspaceDir = opts.workspaceDir;
+        this.now = opts.now ?? (() => new Date().toISOString());
+    }
+    rootDir() {
+        return join(this.workspaceDir, ARTIFACTS_DIR_NAME);
+    }
+    existingSlugs() {
+        const root = this.rootDir();
+        if (!existsSync(root))
+            return new Set();
+        return new Set(readdirSync(root, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => e.name));
+    }
+    handleFor(slug, kind, name) {
+        const dir = join(this.rootDir(), slug);
+        return {
+            slug, kind, name, dir,
+            uri: `artifact://${slug}`,
+            primaryPath: join(dir, PRIMARY_FILE),
+            metadataPath: join(dir, 'metadata.json'),
+            provenancePath: join(dir, 'provenance.json'),
+            readmePath: join(dir, 'README.md'),
+        };
+    }
+    atomicWrite(path, content, mode = 0o600) {
+        const tmp = `${path}.tmp`;
+        writeFileSync(tmp, content, { mode });
+        chmodSync(tmp, mode);
+        renameSync(tmp, path);
+    }
+    readMetadata(path) {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    readProvenance(path) {
+        if (!existsSync(path))
+            return [];
+        try {
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    fileStats(dir) {
+        const snap = takeSnapshot(dir);
+        return [...snap.entries()]
+            .filter(([p]) => p !== 'metadata.json' && p !== 'provenance.json' && p !== 'README.md')
+            .map(([path, { sizeBytes }]) => ({ path, sizeBytes }));
+    }
+    async create(kind, name) {
+        if (!ARTIFACT_KINDS.includes(kind))
+            throw new ArtifactKindRejected(kind);
+        mkdirSync(this.rootDir(), { recursive: true, mode: 0o700 });
+        const base = deriveSlug(name);
+        const slug = nextCollisionSlug(base, this.existingSlugs());
+        const handle = this.handleFor(slug, kind, name);
+        // Use mkdirSync (non-recursive) on the artifact dir for race detection,
+        // but the parent is created above; if this throws EEXIST, retry with bumped slug.
+        try {
+            mkdirSync(handle.dir, { mode: 0o700 });
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                // Race — recurse with refreshed slug set
+                return this.create(kind, name);
+            }
+            throw err;
+        }
+        const ts = this.now();
+        const meta = {
+            _schema: 1, slug, kind, name,
+            created_at: ts, last_updated_at: ts,
+            turn_count: 0, primary_file: PRIMARY_FILE,
+            uri: handle.uri,
+        };
+        this.atomicWrite(handle.metadataPath, JSON.stringify(meta, null, 2));
+        this.atomicWrite(handle.primaryPath, '');
+        this.atomicWrite(handle.provenancePath, '[]');
+        this.atomicWrite(handle.readmePath, renderReadme(meta, [], this.fileStats(handle.dir)));
+        return handle;
+    }
+    async update(handle, files) {
+        if (!existsSync(handle.dir))
+            throw new ArtifactNotFound(handle.slug);
+        for (const f of files) {
+            const normalized = normalize(f.path);
+            if (!f.path || !normalized || normalized === '.' ||
+                normalized.startsWith('..') || normalized.startsWith('/') ||
+                normalized.includes('\0')) {
+                throw new Error(`Bad FileWrite path: ${f.path}`);
+            }
+        }
+        const before = takeSnapshot(handle.dir);
+        for (const f of files) {
+            const abs = join(handle.dir, f.path);
+            mkdirSync(join(abs, '..'), { recursive: true, mode: 0o700 });
+            this.atomicWrite(abs, f.content);
+        }
+        const after = takeSnapshot(handle.dir);
+        const diff = diffSnapshots(before, after);
+        const filesTouched = [...new Set([...diff.added, ...diff.modified])]
+            .filter(p => p !== 'metadata.json' && p !== 'provenance.json' && p !== 'README.md')
+            .sort();
+        // Bump metadata (last_updated_at; turn_count incremented by recordTurn)
+        const meta = this.readMetadata(handle.metadataPath);
+        meta.last_updated_at = this.now();
+        this.atomicWrite(handle.metadataPath, JSON.stringify(meta, null, 2));
+        const prov = this.readProvenance(handle.provenancePath);
+        this.atomicWrite(handle.readmePath, renderReadme(meta, prov, this.fileStats(handle.dir)));
+        return { files_touched: filesTouched };
+    }
+    async recordTurn(handle, entry) {
+        if (!existsSync(handle.dir))
+            throw new ArtifactNotFound(handle.slug);
+        const prov = this.readProvenance(handle.provenancePath);
+        const ts = entry.ts ?? this.now();
+        const fullEntry = {
+            _schema: 1, ts,
+            action: entry.action,
+            turn_id: entry.turn_id,
+            user_prompt: entry.user_prompt,
+            files_touched: entry.files_touched,
+            ...(entry.agent_turn_id !== undefined ? { agent_turn_id: entry.agent_turn_id } : {}),
+            ...(entry.scratchpad_name !== undefined ? { scratchpad_name: entry.scratchpad_name } : {}),
+        };
+        prov.push(fullEntry);
+        this.atomicWrite(handle.provenancePath, JSON.stringify(prov, null, 2));
+        // Bump metadata
+        const meta = this.readMetadata(handle.metadataPath);
+        meta.turn_count = prov.length;
+        meta.last_updated_at = ts;
+        this.atomicWrite(handle.metadataPath, JSON.stringify(meta, null, 2));
+        this.atomicWrite(handle.readmePath, renderReadme(meta, prov, this.fileStats(handle.dir)));
+    }
+    async list() {
+        const root = this.rootDir();
+        if (!existsSync(root))
+            return [];
+        const handles = [];
+        for (const slug of this.existingSlugs()) {
+            const metaPath = join(root, slug, 'metadata.json');
+            if (!existsSync(metaPath))
+                continue;
+            try {
+                const meta = this.readMetadata(metaPath);
+                const h = this.handleFor(meta.slug, meta.kind, meta.name);
+                handles.push({ handle: h, created_at: meta.created_at });
+            }
+            catch { /* skip malformed */ }
+        }
+        handles.sort((a, b) => b.created_at.localeCompare(a.created_at));
+        return handles.map(x => x.handle);
+    }
+    async get(slug) {
+        const metaPath = join(this.rootDir(), slug, 'metadata.json');
+        if (!existsSync(metaPath))
+            return null;
+        const meta = this.readMetadata(metaPath);
+        return this.handleFor(meta.slug, meta.kind, meta.name);
+    }
+    async remove(slug, confirm) {
+        if (confirm !== true)
+            throw new Error(`/artifacts remove requires --confirm`);
+        if (!slug || slug.includes('/') || slug.includes('..') || slug === '.') {
+            throw new ArtifactNotFound(slug);
+        }
+        const dir = join(this.rootDir(), slug);
+        if (!existsSync(dir))
+            throw new ArtifactNotFound(slug);
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/packages/coworker-artifacts/dist/dir-snapshot.d.ts

@@ -0,0 +1,7 @@
+import type { DirSnapshot } from './types.js';
+export declare function takeSnapshot(dir: string): DirSnapshot;
+export declare function diffSnapshots(before: DirSnapshot, after: DirSnapshot): {
+    added: string[];
+    modified: string[];
+    removed: string[];
+};

package/packages/coworker-artifacts/dist/dir-snapshot.js

@@ -0,0 +1,54 @@
+// packages/coworker-artifacts/src/dir-snapshot.ts
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+export function takeSnapshot(dir) {
+    const out = new Map();
+    if (!existsSync(dir))
+        return out;
+    walk(dir, dir, out);
+    return out;
+}
+function walk(root, current, out) {
+    let entries;
+    try {
+        entries = readdirSync(current, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const abs = join(current, entry.name);
+        if (entry.isDirectory()) {
+            walk(root, abs, out);
+        }
+        else if (entry.isFile()) {
+            const stat = statSync(abs, { bigint: true });
+            const rel = relative(root, abs).split(sep).join('/');
+            out.set(rel, {
+                mtimeNs: stat.mtimeNs,
+                sizeBytes: Number(stat.size),
+            });
+        }
+    }
+}
+export function diffSnapshots(before, after) {
+    const added = [];
+    const modified = [];
+    const removed = [];
+    for (const [path, a] of after) {
+        const b = before.get(path);
+        if (!b)
+            added.push(path);
+        else if (b.mtimeNs !== a.mtimeNs || b.sizeBytes !== a.sizeBytes)
+            modified.push(path);
+    }
+    for (const path of before.keys()) {
+        if (!after.has(path))
+            removed.push(path);
+    }
+    return {
+        added: added.sort(),
+        modified: modified.sort(),
+        removed: removed.sort(),
+    };
+}

package/packages/coworker-artifacts/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class ArtifactNotFound extends Error {
+    readonly slug: string;
+    constructor(slug: string);
+}
+export declare class ArtifactKindRejected extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+export declare class ArtifactUriMalformed extends Error {
+    readonly uri: string;
+    readonly reason: string;
+    constructor(uri: string, reason: string);
+}
+export declare class ArtifactSlugCollision extends Error {
+    readonly base: string;
+    readonly attempts: number;
+    constructor(base: string, attempts: number);
+}

package/packages/coworker-artifacts/dist/errors.js

@@ -0,0 +1,37 @@
+// packages/coworker-artifacts/src/errors.ts
+export class ArtifactNotFound extends Error {
+    slug;
+    constructor(slug) {
+        super(`Artifact not found: ${slug}. /artifacts list to see available.`);
+        this.slug = slug;
+        this.name = 'ArtifactNotFound';
+    }
+}
+export class ArtifactKindRejected extends Error {
+    kind;
+    constructor(kind) {
+        super(`Artifact kind '${kind}' is not supported. v1 ships only 'report'.`);
+        this.kind = kind;
+        this.name = 'ArtifactKindRejected';
+    }
+}
+export class ArtifactUriMalformed extends Error {
+    uri;
+    reason;
+    constructor(uri, reason) {
+        super(`Bad artifact URI ${uri}: ${reason}.`);
+        this.uri = uri;
+        this.reason = reason;
+        this.name = 'ArtifactUriMalformed';
+    }
+}
+export class ArtifactSlugCollision extends Error {
+    base;
+    attempts;
+    constructor(base, attempts) {
+        super(`Slug collision: '${base}' has ${attempts} colliding suffixes (-2…-${attempts + 1}). Pick a different name.`);
+        this.base = base;
+        this.attempts = attempts;
+        this.name = 'ArtifactSlugCollision';
+    }
+}

package/packages/coworker-artifacts/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './slug.js';
+export * from './dir-snapshot.js';
+export * from './resolve-uri.js';
+export * from './readme-renderer.js';
+export * from './artifact-store.js';

package/packages/coworker-artifacts/dist/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './slug.js';
+export * from './dir-snapshot.js';
+export * from './resolve-uri.js';
+export * from './readme-renderer.js';
+export * from './artifact-store.js';

package/packages/coworker-artifacts/dist/readme-renderer.d.ts

@@ -0,0 +1,5 @@
+import type { ArtifactMetadata, Provenance } from './types.js';
+export declare function renderReadme(metadata: ArtifactMetadata, provenance: Provenance, fileStats: Array<{
+    path: string;
+    sizeBytes: number;
+}>): string;

package/packages/coworker-artifacts/dist/readme-renderer.js

@@ -0,0 +1,47 @@
+const UNITS = ['B', 'KB', 'MB', 'GB'];
+function humanSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < UNITS.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(1)} ${UNITS[unit]}`;
+}
+function escapeMarkdownPipe(s) {
+    return s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+export function renderReadme(metadata, provenance, fileStats) {
+    const firstTurn = provenance[0]?.turn_id ?? '';
+    const lastTurn = provenance.length > 0 ? provenance[provenance.length - 1].turn_id : '';
+    const lines = [];
+    lines.push(`# ${metadata.name}`);
+    lines.push('');
+    lines.push(`**Kind:** ${metadata.kind}`);
+    lines.push(`**URI:** \`${metadata.uri}\``);
+    lines.push(`**Created:** ${metadata.created_at}${firstTurn ? ` (turn \`${firstTurn}\`)` : ''}`);
+    lines.push(`**Last updated:** ${metadata.last_updated_at}${lastTurn ? ` (turn \`${lastTurn}\`)` : ''}`);
+    lines.push(`**Turns:** ${metadata.turn_count}`);
+    lines.push('');
+    lines.push('## Files');
+    lines.push('');
+    if (fileStats.length === 0) {
+        lines.push('(none)');
+    }
+    else {
+        for (const f of fileStats) {
+            lines.push(`- \`${f.path}\` — ${humanSize(f.sizeBytes)}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Provenance');
+    lines.push('');
+    lines.push('| # | ts | action | turn | prompt |');
+    lines.push('|---|---|---|---|---|');
+    provenance.forEach((e, i) => {
+        lines.push(`| ${i + 1} | ${e.ts} | ${e.action} | ${e.turn_id} | ${escapeMarkdownPipe(e.user_prompt)} |`);
+    });
+    return lines.join('\n') + '\n';
+}

package/packages/coworker-artifacts/dist/resolve-uri.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedArtifactUri } from './types.js';
+export declare const ARTIFACT_URI_SCHEME = "artifact://";
+export declare function resolveArtifactUri(uri: string, workspaceDir: string): ResolvedArtifactUri;

package/packages/coworker-artifacts/dist/resolve-uri.js

@@ -0,0 +1,29 @@
+// packages/coworker-artifacts/src/resolve-uri.ts
+import { join } from 'node:path';
+import { ArtifactUriMalformed } from './errors.js';
+export const ARTIFACT_URI_SCHEME = 'artifact://';
+const SLUG_REGEX = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/;
+export function resolveArtifactUri(uri, workspaceDir) {
+    if (!uri.startsWith(ARTIFACT_URI_SCHEME)) {
+        throw new ArtifactUriMalformed(uri, `must start with ${ARTIFACT_URI_SCHEME}`);
+    }
+    const slug = uri.slice(ARTIFACT_URI_SCHEME.length);
+    if (!slug)
+        throw new ArtifactUriMalformed(uri, 'empty slug');
+    if (slug.includes('..'))
+        throw new ArtifactUriMalformed(uri, 'path traversal');
+    if (slug.length > 64)
+        throw new ArtifactUriMalformed(uri, 'slug exceeds 64 chars');
+    if (!SLUG_REGEX.test(slug)) {
+        throw new ArtifactUriMalformed(uri, 'slug must match ^[a-z0-9][a-z0-9-]*[a-z0-9]$');
+    }
+    const dir = join(workspaceDir, '.otto', 'artifacts', slug);
+    return {
+        slug,
+        dir,
+        primaryPath: join(dir, 'report.md'),
+        metadataPath: join(dir, 'metadata.json'),
+        provenancePath: join(dir, 'provenance.json'),
+        readmePath: join(dir, 'README.md'),
+    };
+}

package/packages/coworker-artifacts/dist/slug.d.ts

@@ -0,0 +1,4 @@
+export declare const MAX_SLUG_LENGTH = 64;
+export declare const MAX_COLLISION_ATTEMPTS = 100;
+export declare function deriveSlug(name: string): string;
+export declare function nextCollisionSlug(base: string, taken: Set<string>): string;

package/packages/coworker-artifacts/dist/slug.js

@@ -0,0 +1,32 @@
+// packages/coworker-artifacts/src/slug.ts
+import { ArtifactSlugCollision } from './errors.js';
+export const MAX_SLUG_LENGTH = 64;
+export const MAX_COLLISION_ATTEMPTS = 100;
+export function deriveSlug(name) {
+    let s = name.toLowerCase();
+    // Strip diacritics (NFKD + remove combining marks U+0300–U+036F)
+    s = s.normalize('NFKD').replace(/[̀-ͯ]/g, '');
+    // Replace non a-z 0-9 with dash
+    s = s.replace(/[^a-z0-9]+/g, '-');
+    // Collapse runs of dashes
+    s = s.replace(/-+/g, '-');
+    // Trim leading/trailing dashes
+    s = s.replace(/^-+|-+$/g, '');
+    // Truncate
+    if (s.length > MAX_SLUG_LENGTH)
+        s = s.slice(0, MAX_SLUG_LENGTH).replace(/-+$/, '');
+    // Fallback if empty
+    if (!s)
+        s = `artifact-${Date.now().toString(36)}`;
+    return s;
+}
+export function nextCollisionSlug(base, taken) {
+    if (!taken.has(base))
+        return base;
+    for (let n = 2; n <= MAX_COLLISION_ATTEMPTS + 1; n++) {
+        const candidate = `${base}-${n}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    throw new ArtifactSlugCollision(base, MAX_COLLISION_ATTEMPTS);
+}

package/packages/coworker-artifacts/dist/types.d.ts

@@ -0,0 +1,52 @@
+export type ArtifactKind = 'report';
+export declare const ARTIFACT_KINDS: readonly ["report"];
+export interface ArtifactHandle {
+    slug: string;
+    kind: ArtifactKind;
+    name: string;
+    dir: string;
+    uri: string;
+    primaryPath: string;
+    metadataPath: string;
+    provenancePath: string;
+    readmePath: string;
+}
+export interface ArtifactMetadata {
+    _schema: 1;
+    slug: string;
+    kind: ArtifactKind;
+    name: string;
+    created_at: string;
+    last_updated_at: string;
+    turn_count: number;
+    primary_file: string;
+    uri: string;
+}
+export interface TurnEntry {
+    _schema: 1;
+    ts: string;
+    action: 'create' | 'update';
+    turn_id: string;
+    agent_turn_id?: string;
+    user_prompt: string;
+    scratchpad_name?: string;
+    files_touched: string[];
+}
+export type Provenance = TurnEntry[];
+export interface DirSnapshotEntry {
+    mtimeNs: bigint;
+    sizeBytes: number;
+}
+export type DirSnapshot = Map<string, DirSnapshotEntry>;
+export interface FileWrite {
+    path: string;
+    content: string;
+}
+export interface ResolvedArtifactUri {
+    slug: string;
+    dir: string;
+    primaryPath: string;
+    metadataPath: string;
+    provenancePath: string;
+    readmePath: string;
+}

package/packages/coworker-artifacts/dist/types.js

@@ -0,0 +1 @@
+export const ARTIFACT_KINDS = ['report'];

package/packages/coworker-artifacts/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@otto/coworker-artifacts",
+  "version": "0.0.1",
+  "description": "Otto co-worker package: coworker-artifacts",
+  "type": "module",
+  "otto": { "linkable": true, "scope": "@otto", "name": "coworker-artifacts" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "dependencies": {
+    "@otto/coworker-utils": "*"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:publish": "tsc -p tsconfig.publish.json"
+  },
+  "files": ["dist"]
+}