chainlesschain 0.162.156 → 0.162.158

package/src/gateways/ws/artifact-protocol.js

@@ -0,0 +1,219 @@
+/**
+ * artifact WS protocol — exposes the agent-published deliverable store
+ * (lib/artifact-store.js, P1 #10) to web-panel / IDE clients so an
+ * "Artifacts" panel can list deliverables, preview them (text inline /
+ * images as base64), and manage retention.
+ *
+ * Routes (request → reply):
+ *   artifact-list    {session?, kind?}         → {type:"artifact-list", artifacts}
+ *   artifact-show    {artifactId}              → {type:"artifact-show", artifact}
+ *   artifact-content {artifactId, maxBytes?}   → {type:"artifact-content", artifactId,
+ *                                                 mime, encoding, content, size,
+ *                                                 truncated, previewable}
+ *   artifact-remove  {artifactId}              → {type:"artifact-remove", removed, found}
+ *   artifact-clean   {}                        → {type:"artifact-clean", removed}
+ *
+ * Preview policy: text mimes stream as utf8 (capped, `truncated` flagged);
+ * images as base64 (hard cap — an oversized image reports previewable:false
+ * instead of flooding the socket); everything else is metadata-only
+ * (previewable:false, the user has `cc artifacts open <id>` locally).
+ *
+ * The stored-copy filename comes from index.jsonl; serving is refused if it
+ * is not a plain basename, so a hand-tampered index row can never turn the
+ * content route into an arbitrary-file read.
+ */
+
+import path from "node:path";
+import { readFileSync, statSync } from "node:fs";
+
+/** Text preview cap (utf8 chars ≈ bytes for the common case). */
+export const TEXT_PREVIEW_CAP = 256 * 1024;
+/** Image preview cap — beyond this the panel gets metadata only. */
+export const IMAGE_PREVIEW_CAP = 8 * 1024 * 1024;
+
+const TEXT_APPLICATION_MIMES = new Set([
+  "application/json",
+  "application/yaml",
+  "application/xml",
+]);
+
+async function loadStore() {
+  const { ArtifactStore } = await import("../../lib/artifact-store.js");
+  return new ArtifactStore();
+}
+
+function sendError(server, id, ws, code, message) {
+  server._send(ws, { id, type: "error", code, message });
+}
+
+/** Classify how (whether) an artifact can be previewed inline. */
+export function previewKindForMime(mime) {
+  const m = String(mime || "").toLowerCase();
+  if (m.startsWith("text/") || TEXT_APPLICATION_MIMES.has(m)) return "text";
+  if (m.startsWith("image/")) return "image";
+  return "none";
+}
+
+export async function handleArtifactList(server, id, ws, message) {
+  try {
+    const store = await loadStore();
+    let artifacts = store.list({ sessionId: message.session || undefined });
+    if (message.kind) {
+      artifacts = artifacts.filter((e) => e.kind === String(message.kind));
+    }
+    server._send(ws, { id, type: "artifact-list", artifacts });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_LIST_FAILED", err.message);
+  }
+}
+
+export async function handleArtifactShow(server, id, ws, message) {
+  try {
+    if (!message.artifactId) {
+      return sendError(server, id, ws, "NO_ARTIFACT_ID", "artifactId required");
+    }
+    const store = await loadStore();
+    const entry = store.get(message.artifactId);
+    if (!entry) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "ARTIFACT_NOT_FOUND",
+        `Artifact not found: ${message.artifactId}`,
+      );
+    }
+    server._send(ws, {
+      id,
+      type: "artifact-show",
+      artifact: { ...entry, storedPath: store.storedPath(entry) },
+    });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_SHOW_FAILED", err.message);
+  }
+}
+
+export async function handleArtifactContent(server, id, ws, message) {
+  try {
+    if (!message.artifactId) {
+      return sendError(server, id, ws, "NO_ARTIFACT_ID", "artifactId required");
+    }
+    const store = await loadStore();
+    const entry = store.get(message.artifactId);
+    if (!entry) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "ARTIFACT_NOT_FOUND",
+        `Artifact not found: ${message.artifactId}`,
+      );
+    }
+    // Traversal guard: the stored filename must be a plain basename. A
+    // tampered index row ("file":"../../secret") must not read outside the
+    // files dir.
+    if (
+      !entry.file ||
+      entry.file !== path.basename(entry.file) ||
+      entry.file.includes("..")
+    ) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "ARTIFACT_BAD_FILE",
+        "artifact index row has a non-basename stored filename — refusing to serve it",
+      );
+    }
+    const previewKind = previewKindForMime(entry.mime);
+    const base = {
+      id,
+      type: "artifact-content",
+      artifactId: entry.id,
+      mime: entry.mime,
+      size: entry.size,
+    };
+    if (previewKind === "none") {
+      return server._send(ws, {
+        ...base,
+        previewable: false,
+        reason: `no inline preview for ${entry.mime} — use \`cc artifacts open ${entry.id}\` locally`,
+      });
+    }
+    const storedPath = store.storedPath(entry);
+    let actualSize;
+    try {
+      actualSize = statSync(storedPath).size;
+    } catch {
+      return sendError(
+        server,
+        id,
+        ws,
+        "ARTIFACT_FILE_MISSING",
+        `stored copy is missing: ${entry.file}`,
+      );
+    }
+    if (previewKind === "image") {
+      if (actualSize > IMAGE_PREVIEW_CAP) {
+        return server._send(ws, {
+          ...base,
+          previewable: false,
+          reason: `image exceeds the ${IMAGE_PREVIEW_CAP} byte preview cap`,
+        });
+      }
+      const body = readFileSync(storedPath);
+      return server._send(ws, {
+        ...base,
+        previewable: true,
+        encoding: "base64",
+        truncated: false,
+        content: body.toString("base64"),
+      });
+    }
+    // text
+    const cap = Math.min(
+      Number(message.maxBytes) > 0 ? Number(message.maxBytes) : TEXT_PREVIEW_CAP,
+      TEXT_PREVIEW_CAP,
+    );
+    const text = readFileSync(storedPath, "utf-8");
+    const truncated = text.length > cap;
+    server._send(ws, {
+      ...base,
+      previewable: true,
+      encoding: "utf8",
+      truncated,
+      content: truncated ? text.slice(0, cap) : text,
+    });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_CONTENT_FAILED", err.message);
+  }
+}
+
+export async function handleArtifactRemove(server, id, ws, message) {
+  try {
+    if (!message.artifactId) {
+      return sendError(server, id, ws, "NO_ARTIFACT_ID", "artifactId required");
+    }
+    const store = await loadStore();
+    const found = store.remove(message.artifactId);
+    server._send(ws, {
+      id,
+      type: "artifact-remove",
+      artifactId: message.artifactId,
+      removed: found ? message.artifactId : null,
+      found,
+    });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_REMOVE_FAILED", err.message);
+  }
+}
+
+export async function handleArtifactClean(server, id, ws, message) {
+  try {
+    const store = await loadStore();
+    const { removed } = store.cleanupExpired();
+    server._send(ws, { id, type: "artifact-clean", removed });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_CLEAN_FAILED", err.message);
+  }
+}

package/src/gateways/ws/message-dispatcher.js

@@ -185,6 +185,12 @@ export function createWsMessageDispatcher(server) {
         "bg-stop": () => server._handleBgStop(clientId, id, ws, message),
         "bg-rename": () => server._handleBgRename(id, ws, message),
         "bg-resume": () => server._handleBgResume(id, ws, message),
+        "artifact-list": () => server._handleArtifactList(id, ws, message),
+        "artifact-show": () => server._handleArtifactShow(id, ws, message),
+        "artifact-content": () =>
+          server._handleArtifactContent(id, ws, message),
+        "artifact-remove": () => server._handleArtifactRemove(id, ws, message),
+        "artifact-clean": () => server._handleArtifactClean(id, ws, message),
         "chat.intent.understand": () =>
           server._handleChatIntentUnderstand(id, ws, message),
         "chat.intent.understand-stream": () =>

package/src/gateways/ws/ws-server.js

@@ -106,6 +106,13 @@ import {
   handleBgStopTurn,
   handleBgView,
 } from "./background-agent-protocol.js";
+import {
+  handleArtifactClean,
+  handleArtifactContent,
+  handleArtifactList,
+  handleArtifactRemove,
+  handleArtifactShow,
+} from "./artifact-protocol.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -717,6 +724,31 @@ export class ChainlessChainWSServer extends EventEmitter {
     return handleBgResume(this, id, ws, message);
   }
 
+  /** @private — list agent-published artifacts (metadata only) */
+  async _handleArtifactList(id, ws, message) {
+    return handleArtifactList(this, id, ws, message);
+  }
+
+  /** @private — one artifact's metadata + stored path */
+  async _handleArtifactShow(id, ws, message) {
+    return handleArtifactShow(this, id, ws, message);
+  }
+
+  /** @private — inline preview content (text utf8 / image base64, capped) */
+  async _handleArtifactContent(id, ws, message) {
+    return handleArtifactContent(this, id, ws, message);
+  }
+
+  /** @private — remove one artifact (stored copy + index row) */
+  async _handleArtifactRemove(id, ws, message) {
+    return handleArtifactRemove(this, id, ws, message);
+  }
+
+  /** @private — drop expired artifacts (TTL) */
+  async _handleArtifactClean(id, ws, message) {
+    return handleArtifactClean(this, id, ws, message);
+  }
+
   /** @private */
   async _handleCompressionStats(id, ws, message) {
     return handleCompressionStats(this, id, ws, message);

package/src/index.js

@@ -162,6 +162,9 @@ import { registerAgendaCommand } from "./commands/agenda.js";
 // Batch: dynamic worktree batch — split a change into parallel units (第四阶段 #4)
 import { registerBatchCommand } from "./commands/batch.js";
 
+// Artifacts: agent-published deliverable store (P1 #10)
+import { registerArtifactsCommand } from "./commands/artifacts.js";
+
 // Web UI
 import { registerUiCommand } from "./commands/ui.js";
 import { registerPackCommand } from "./commands/pack.js";
@@ -598,6 +601,9 @@ export function createProgram(opts = {}) {
   // Batch: dynamic worktree batch
   registerBatchCommand(program);
 
+  // Artifacts: agent-published deliverable store
+  registerArtifactsCommand(program);
+
   // Web UI
   registerUiCommand(program);
 

package/src/lib/accessibility.js

@@ -0,0 +1,55 @@
+/**
+ * `cc agent --ax-screen-reader` — screen-reader friendly output.
+ *
+ * Screen readers linearize the terminal: colors are invisible, and anything
+ * that repaints in place (the context status line) reads as noisy duplicate
+ * lines. This mode therefore:
+ *   - forces the `mono` theme (chalk level 0 — no ANSI color codes) in the
+ *     interactive REPL (consumed via CC_SCREEN_READER in agent-repl.js);
+ *   - disables the repainting status line (reuses the existing
+ *     CC_STATUSLINE=0 kill-switch).
+ * Headless (-p) text output is already plain sequential lines.
+ *
+ * Ambient activation: CC_SCREEN_READER=1 (so wrappers/launchers can turn it
+ * on without threading a flag through every entry point).
+ */
+
+/** env switches applied by --ax-screen-reader. */
+export const SCREEN_READER_SWITCHES = Object.freeze({
+  CC_SCREEN_READER: "1", // REPL: force mono theme / no ANSI decorations
+  CC_STATUSLINE: "0", // in-place repainting status line off
+});
+
+/**
+ * Apply screen-reader mode to an env (default process.env).
+ * @returns {string[]} the switch names applied (for the startup notice)
+ */
+export function applyScreenReaderMode(env = process.env) {
+  for (const [k, v] of Object.entries(SCREEN_READER_SWITCHES)) {
+    env[k] = v;
+  }
+  return Object.keys(SCREEN_READER_SWITCHES);
+}
+
+/**
+ * Whether screen-reader mode is requested — the explicit `--ax-screen-reader`
+ * flag or the ambient CC_SCREEN_READER env var (1 / true / yes / on).
+ * @param {{ axScreenReader?: boolean }} [opts]
+ * @param {object} [env=process.env]
+ * @returns {boolean}
+ */
+export function screenReaderRequested(opts = {}, env = process.env) {
+  if (opts && opts.axScreenReader === true) return true;
+  return screenReaderActive(env);
+}
+
+/**
+ * Whether screen-reader mode is ACTIVE in the environment (what downstream
+ * consumers — the REPL theme init — should check).
+ * @param {object} [env=process.env]
+ * @returns {boolean}
+ */
+export function screenReaderActive(env = process.env) {
+  const raw = env.CC_SCREEN_READER;
+  return raw != null && /^(1|true|yes|on)$/i.test(String(raw).trim());
+}

package/src/lib/artifact-store.js

@@ -0,0 +1,236 @@
+/**
+ * ArtifactStore — durable home for agent DELIVERABLES (gap-analysis P1 #10).
+ *
+ * An agent run produces important files — a Markdown report, a patch, a
+ * screenshot, test logs, review findings JSON — that otherwise live as loose
+ * paths the user has to remember. `publish_artifact` copies such a file into
+ * `~/.chainlesschain/artifacts/` with metadata (title, kind, mime, sha256,
+ * session), so:
+ *   - the session transcript only records the small METADATA object (the tool
+ *     result), never the file body;
+ *   - `cc artifacts` lists/inspects/cleans them across sessions;
+ *   - web-panel / remote surfaces can later serve previews from one place.
+ *
+ * Layout:
+ *   ~/.chainlesschain/artifacts/index.jsonl   one metadata row per artifact
+ *   ~/.chainlesschain/artifacts/files/<id><ext>  the stored copy
+ *
+ * Per-row tolerant JSONL (a corrupt line never poisons the store); injected
+ * clock + dir for unit tests; TTL-based expiry with an explicit cleanup call
+ * (`cc artifacts clean` / opportunistic on publish).
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+
+export const ARTIFACT_KINDS = Object.freeze([
+  "report",
+  "patch",
+  "screenshot",
+  "log",
+  "data",
+  "other",
+]);
+
+/** Copy-size guard: an "artifact" is a deliverable, not a build tree. */
+export const MAX_ARTIFACT_BYTES = 100 * 1024 * 1024; // 100 MB
+
+/** Default retention before `clean` removes an artifact. */
+export const DEFAULT_TTL_DAYS = 30;
+
+const MIME_BY_EXT = Object.freeze({
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".json": "application/json",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".csv": "text/csv",
+  ".xml": "application/xml",
+  ".yaml": "application/yaml",
+  ".yml": "application/yaml",
+  ".patch": "text/x-patch",
+  ".diff": "text/x-patch",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+});
+
+export function artifactsDir(homedir = os.homedir()) {
+  // Test/deployment override (same convention as CC_BACKGROUND_AGENTS_DIR).
+  if (process.env.CC_ARTIFACTS_DIR) return process.env.CC_ARTIFACTS_DIR;
+  return path.join(homedir, ".chainlesschain", "artifacts");
+}
+
+function mimeForExt(ext) {
+  return (
+    MIME_BY_EXT[String(ext || "").toLowerCase()] || "application/octet-stream"
+  );
+}
+
+function normalizeKind(kind) {
+  const k = typeof kind === "string" ? kind.trim().toLowerCase() : "";
+  return ARTIFACT_KINDS.includes(k) ? k : "other";
+}
+
+export class ArtifactStore {
+  constructor({ dir = null, now = () => Date.now() } = {}) {
+    this.dir = dir || artifactsDir();
+    this._now = typeof now === "function" ? now : () => now;
+  }
+
+  _indexFile() {
+    return path.join(this.dir, "index.jsonl");
+  }
+
+  _filesDir() {
+    return path.join(this.dir, "files");
+  }
+
+  _ensureDirs() {
+    fs.mkdirSync(this._filesDir(), { recursive: true });
+  }
+
+  /**
+   * Publish a file as an artifact (copy + metadata row).
+   * @param {{ filePath: string, title?: string, kind?: string,
+   *           sessionId?: string|null, ttlDays?: number }} opts
+   * @returns {object} the metadata entry (what the tool returns — no body)
+   */
+  publish({ filePath, title, kind, sessionId = null, ttlDays } = {}) {
+    if (!filePath) throw new Error("publish requires a filePath");
+    const abs = path.resolve(filePath);
+    let stat;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      throw new Error(`artifact source not found: ${abs}`);
+    }
+    if (!stat.isFile()) {
+      throw new Error(`artifact source is not a regular file: ${abs}`);
+    }
+    if (stat.size > MAX_ARTIFACT_BYTES) {
+      throw new Error(
+        `artifact too large (${stat.size} bytes > ${MAX_ARTIFACT_BYTES}); artifacts are deliverables, not build output`,
+      );
+    }
+    const body = fs.readFileSync(abs);
+    const sha256 = crypto.createHash("sha256").update(body).digest("hex");
+    const ext = path.extname(abs);
+    const id = `art_${this._now().toString(36)}_${crypto
+      .randomBytes(4)
+      .toString("hex")}`;
+    const days = Number.isFinite(Number(ttlDays))
+      ? Math.max(1, Number(ttlDays))
+      : DEFAULT_TTL_DAYS;
+    const createdAt = this._now();
+    const entry = {
+      id,
+      title: String(title || path.basename(abs)),
+      kind: normalizeKind(kind),
+      mime: mimeForExt(ext),
+      size: stat.size,
+      sha256,
+      sourcePath: abs,
+      file: `${id}${ext}`,
+      sessionId: sessionId ? String(sessionId) : null,
+      createdAt: new Date(createdAt).toISOString(),
+      expiresAt: new Date(createdAt + days * 24 * 60 * 60 * 1000).toISOString(),
+    };
+    this._ensureDirs();
+    fs.writeFileSync(path.join(this._filesDir(), entry.file), body);
+    fs.appendFileSync(this._indexFile(), JSON.stringify(entry) + "\n", "utf-8");
+    return entry;
+  }
+
+  /** All (non-corrupt) metadata rows, oldest first. */
+  list({ sessionId } = {}) {
+    let raw;
+    try {
+      raw = fs.readFileSync(this._indexFile(), "utf-8");
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const e = JSON.parse(t);
+        if (e && typeof e === "object" && e.id) out.push(e);
+      } catch {
+        /* per-row tolerance — a corrupt line never poisons the store */
+      }
+    }
+    return sessionId ? out.filter((e) => e.sessionId === sessionId) : out;
+  }
+
+  /** One entry by id (or null). */
+  get(id) {
+    return this.list().find((e) => e.id === id) || null;
+  }
+
+  /** Absolute path of an artifact's stored copy (or null). */
+  storedPath(idOrEntry) {
+    const entry =
+      typeof idOrEntry === "object" && idOrEntry
+        ? idOrEntry
+        : this.get(idOrEntry);
+    if (!entry) return null;
+    return path.join(this._filesDir(), entry.file);
+  }
+
+  /** Remove one artifact (file + index row). @returns {boolean} found */
+  remove(id) {
+    const entries = this.list();
+    const target = entries.find((e) => e.id === id);
+    if (!target) return false;
+    try {
+      fs.rmSync(this.storedPath(target), { force: true });
+    } catch {
+      /* best-effort — the index row is the source of truth */
+    }
+    this._rewrite(entries.filter((e) => e.id !== id));
+    return true;
+  }
+
+  /**
+   * Remove expired artifacts (expiresAt in the past).
+   * @returns {{ removed: number }}
+   */
+  cleanupExpired() {
+    const entries = this.list();
+    const now = this._now();
+    const keep = [];
+    let removed = 0;
+    for (const e of entries) {
+      const exp = Date.parse(e.expiresAt || "");
+      if (Number.isFinite(exp) && exp <= now) {
+        try {
+          fs.rmSync(this.storedPath(e), { force: true });
+        } catch {
+          /* best-effort */
+        }
+        removed += 1;
+      } else {
+        keep.push(e);
+      }
+    }
+    if (removed > 0) this._rewrite(keep);
+    return { removed };
+  }
+
+  _rewrite(entries) {
+    this._ensureDirs();
+    const text = entries.map((e) => JSON.stringify(e)).join("\n");
+    fs.writeFileSync(this._indexFile(), text ? text + "\n" : "", "utf-8");
+  }
+}