@awak-app/simy-cli 0.1.1 → 0.1.2

package/src/console/commands.js

@@ -0,0 +1,100 @@
+const HELP_LINES = [
+  "/new                  Start composing a new coding task",
+  "/repos                Choose from authorized local Git repositories",
+  "/scan [path]          Review and authorize a local repository scan",
+  "/repo <owner/name>    Set the GitHub repository for the next task",
+  "/branch <name>        Set the base branch for the next task",
+  "/executor <name>      Select codex or claude",
+  "/attach <path>        Add a local file path to the next task",
+  "/attachments clear    Clear local attachment paths",
+  "/continue <guidance>  Continue a waiting run with human guidance",
+  "/approve <summary>    Approve the local design gate with a recorded note",
+  "/criteria <a | b>     Replace acceptance criteria with explicit values",
+  "/checks <a, b>        Set required CI/security check names",
+  "/recheck              Refresh pull request readiness",
+  "/pause                Pause the active executor process",
+  "/resume               Resume a paused executor process",
+  "/stop                 Stop the selected run",
+];
+
+export function parseConsoleCommand(value) {
+  const text = String(value || "").trim();
+  if (!text) return { type: "empty" };
+  if (!text.startsWith("/")) return { type: "guidance", message: text };
+
+  const separator = text.indexOf(" ");
+  const command = (separator === -1 ? text : text.slice(0, separator)).toLowerCase();
+  const argument = separator === -1 ? "" : text.slice(separator + 1).trim();
+  switch (command) {
+    case "/new":
+      return { type: "new" };
+    case "/repos":
+      return { type: "repositories" };
+    case "/scan":
+      return { type: "scan", root: argument || null };
+    case "/repo":
+      return requiredConfig("repository", argument, "/repo requires owner/name.");
+    case "/branch":
+      return requiredConfig("branch", argument, "/branch requires a branch name.");
+    case "/executor":
+      return argument === "codex" || argument === "claude"
+        ? { type: "configure", field: "backend", value: argument }
+        : { type: "error", message: "/executor requires codex or claude." };
+    case "/attach":
+      return requiredConfig("attachment", argument, "/attach requires a local file path.");
+    case "/attachments":
+      return argument === "clear"
+        ? { type: "configure", field: "clearAttachments", value: true }
+        : { type: "error", message: "/attachments supports only: clear" };
+    case "/continue":
+      return argument
+        ? { type: "guidance", message: argument }
+        : { type: "error", message: "/continue requires guidance." };
+    case "/approve":
+      return argument
+        ? { type: "decision", message: argument, designApproval: true }
+        : { type: "error", message: "/approve requires a design or approval summary." };
+    case "/criteria":
+      return listCommand("acceptanceCriteria", argument, "|");
+    case "/checks":
+      return listCommand("requiredChecks", argument, ",");
+    case "/recheck":
+      return { type: "recheck" };
+    case "/pause":
+      return { type: "pause" };
+    case "/resume":
+      return { type: "resume" };
+    case "/stop":
+      return { type: "stop" };
+    case "/help":
+      return { type: "help" };
+    default:
+      return { type: "error", message: `Unknown command: ${command}` };
+  }
+}
+
+function requiredConfig(field, value, message) {
+  return value ? { type: "configure", field, value } : { type: "error", message };
+}
+
+export function consoleHelpLines() {
+  return [...HELP_LINES];
+}
+
+function listCommand(field, argument, separator) {
+  const values = argument
+    .split(separator)
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (values.length === 0) {
+    return {
+      type: "error",
+      message: `/${field === "requiredChecks" ? "checks" : "criteria"} requires at least one value.`,
+    };
+  }
+  return {
+    type: "decision",
+    message: `Human updated ${field === "requiredChecks" ? "required checks" : "acceptance criteria"}.`,
+    [field]: values,
+  };
+}

package/src/console/index.js

@@ -0,0 +1,25 @@
+import { jsx } from "react/jsx-runtime";
+import { render } from "ink";
+
+import { CodingLoopConsole } from "./app.js";
+
+export async function runCodingLoopConsole(agent, options = {}) {
+  const instance = render(
+    jsx(CodingLoopConsole, {
+      agent,
+      onQuit: options.onQuit,
+    }),
+    {
+      stdin: options.stdin ?? process.stdin,
+      stdout: options.stdout ?? process.stdout,
+      stderr: options.stderr ?? process.stderr,
+      exitOnCtrlC: false,
+      patchConsole: false,
+      debug: false,
+    },
+  );
+  await instance.waitUntilExit();
+}
+
+export { CodingLoopConsole } from "./app.js";
+export { consoleHelpLines, parseConsoleCommand } from "./commands.js";

package/src/index.js

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import { startAgent } from "./agent.js";
+import { openAuthorizationUrl } from "./browser.js";
 import { DEFAULT_WEB_ORIGIN, resolveWebOrigin } from "./web-origin.js";
 
 const argv = process.argv.slice(2);
@@ -13,9 +14,12 @@ if (args.has("--help") || args.has("-h")) {
   console.log(`Usage:
   simy            Start the local SIMY agent
   simy --daemon   Start it in the background
+  simy --no-tui   Start the foreground HTTP agent without the interactive console
 
 Options:
   --daemon, --deamon  Run detached in the background
+  --no-tui            Disable the interactive Coding Loop console
+  --no-open           Do not open the browser when authorization is required
   --port <port>       Bind a specific localhost port
   --host <url>        Connect to a SIMY Web origin (default: ${DEFAULT_WEB_ORIGIN})
 `);
@@ -23,6 +27,7 @@ Options:
 }
 
 const daemon = args.has("--daemon") || args.has("--deamon");
+const interactive = !daemon && !args.has("--no-tui") && process.stdin.isTTY && process.stdout.isTTY;
 const port = readPort(argv);
 let webOrigin;
 try {
@@ -43,7 +48,18 @@ if (daemon && process.env.SIMY_DAEMON_CHILD !== "1") {
   process.exit(0);
 }
 
-await startAgent({ requestedPort: port, daemon, webOrigin });
+const agent = await startAgent({ requestedPort: port, daemon, webOrigin, quiet: interactive });
+if (agent.loginUrl && !args.has("--no-open")) {
+  await openAuthorizationUrl(agent.loginUrl);
+}
+if (interactive) {
+  const { runCodingLoopConsole } = await import("./console/index.js");
+  try {
+    await runCodingLoopConsole(agent);
+  } finally {
+    await closeServer(agent.server);
+  }
+}
 
 function readPort(argv) {
   const index = argv.indexOf("--port");
@@ -65,3 +81,8 @@ function readOption(argv, name) {
   }
   return value;
 }
+
+function closeServer(server) {
+  if (!server.listening) return Promise.resolve();
+  return new Promise((resolve) => server.close(resolve));
+}

package/src/local-attachments.js

@@ -0,0 +1,270 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, realpath, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export const MAX_ATTACHMENT_COUNT = 5;
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export const MAX_ATTACHMENTS_TOTAL_BYTES = 50 * 1024 * 1024;
+const RUN_RETENTION_MS = 24 * 60 * 60 * 1000;
+const SAFE_RUN_ID = /^coding_loop_[A-Za-z0-9_-]+$/;
+const ALLOWED_EXACT_MIME_TYPES = new Set([
+  "application/json",
+  "application/octet-stream",
+  "application/pdf",
+  "application/rtf",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  "application/zip",
+  "application/x-yaml",
+  "image/gif",
+  "image/jpeg",
+  "image/png",
+  "image/svg+xml",
+  "image/webp",
+]);
+
+export function runsRoot(override) {
+  return path.resolve(
+    override || process.env.SIMY_RUNS_ROOT || path.join(os.homedir(), ".simy", "runs"),
+  );
+}
+
+export async function stageRunAttachments({ runId, attachments, manifest, root }) {
+  if (!SAFE_RUN_ID.test(runId)) throw new Error("invalid coding loop run_id");
+  if (!Array.isArray(attachments) || attachments.length === 0) return [];
+  if (attachments.length > MAX_ATTACHMENT_COUNT) {
+    throw new Error(`at most ${MAX_ATTACHMENT_COUNT} attachments are allowed`);
+  }
+  if (manifest !== undefined && (!Array.isArray(manifest) || manifest.length !== attachments.length)) {
+    throw new Error("attachment manifest does not match uploaded files");
+  }
+
+  const runRoot = path.join(runsRoot(root), runId);
+  const inputsRoot = path.join(runRoot, "inputs");
+  await mkdir(runsRoot(root), { recursive: true, mode: 0o700 });
+  await mkdir(runRoot, { mode: 0o700 });
+  await mkdir(inputsRoot, { mode: 0o700 });
+  const staged = [];
+  let totalBytes = 0;
+
+  try {
+    for (const [index, attachment] of attachments.entries()) {
+      const name = safeAttachmentName(attachment.name);
+      const mimeType = normalizeMimeType(attachment.type);
+      if (!isAllowedMimeType(mimeType)) {
+        throw new Error(`attachment ${name} has unsupported MIME type ${mimeType || "unknown"}`);
+      }
+      const bytes = Buffer.from(await attachment.arrayBuffer());
+      if (bytes.length > MAX_ATTACHMENT_BYTES) {
+        throw new Error(`attachment ${name} exceeds the 20 MB limit`);
+      }
+      totalBytes += bytes.length;
+      if (totalBytes > MAX_ATTACHMENTS_TOTAL_BYTES) {
+        throw new Error("attachments exceed the 50 MB total limit");
+      }
+
+      const sha256 = createHash("sha256").update(bytes).digest("hex");
+      if (manifest) verifyManifestEntry(manifest[index], { name, mimeType, size: bytes.length, sha256 });
+
+      const id = `attachment_${randomUUID()}`;
+      const localPath = path.join(inputsRoot, `${id}-${name}`);
+      const handle = await open(localPath, "wx", 0o600);
+      try {
+        await handle.writeFile(bytes);
+      } finally {
+        await handle.close();
+      }
+      staged.push({
+        id,
+        name,
+        mime_type: mimeType,
+        size_bytes: bytes.length,
+        sha256,
+        local_path: localPath,
+        integrity_status: "verified",
+        staged_at: new Date().toISOString(),
+        executor_handoff_status: "pending",
+        delivered_at: null,
+        cleanup_status: "pending",
+        cleaned_at: null,
+        cleanup_error: null,
+        storage: "managed_copy",
+      });
+    }
+    return staged;
+  } catch (error) {
+    await rm(runRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export async function cleanupRunAttachments(attachments) {
+  const localPath = attachments?.find(
+    (item) => item?.storage === "managed_copy" && typeof item?.local_path === "string",
+  )?.local_path;
+  if (!localPath) return;
+  await rm(path.dirname(path.dirname(localPath)), { recursive: true, force: true });
+}
+
+export async function referenceLocalAttachmentPaths(values) {
+  const paths = [...new Set((values || []).map((value) => path.resolve(String(value))))];
+  if (paths.length > MAX_ATTACHMENT_COUNT) {
+    throw new Error(`at most ${MAX_ATTACHMENT_COUNT} attachments are allowed`);
+  }
+  let totalBytes = 0;
+  const attachments = [];
+  for (const value of paths) {
+    const resolved = await realpath(value);
+    const details = await stat(resolved);
+    if (!details.isFile()) throw new Error(`${value} is not a file`);
+    if (details.size > MAX_ATTACHMENT_BYTES) {
+      throw new Error(`${path.basename(resolved)} exceeds the 20 MB limit`);
+    }
+    totalBytes += details.size;
+    if (totalBytes > MAX_ATTACHMENTS_TOTAL_BYTES) {
+      throw new Error("attachments exceed the 50 MB total limit");
+    }
+    const bytes = await readFile(resolved);
+    attachments.push({
+      id: `attachment_${randomUUID()}`,
+      name: safeAttachmentName(path.basename(resolved)),
+      mime_type: inferMimeType(resolved),
+      size_bytes: details.size,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      local_path: resolved,
+      integrity_status: "verified",
+      staged_at: new Date().toISOString(),
+      executor_handoff_status: "pending",
+      delivered_at: null,
+      cleanup_status: "not_required",
+      cleaned_at: null,
+      cleanup_error: null,
+      storage: "source_path",
+    });
+  }
+  return attachments;
+}
+
+export async function cleanupExpiredRuns({ root, now = Date.now() } = {}) {
+  const base = runsRoot(root);
+  let entries;
+  try {
+    entries = await readdir(base, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory() && SAFE_RUN_ID.test(entry.name))
+      .map(async (entry) => {
+        const target = path.join(base, entry.name);
+        const details = await stat(target);
+        if (now - details.mtimeMs > RUN_RETENTION_MS) {
+          await rm(target, { recursive: true, force: true });
+        }
+      }),
+  );
+}
+
+export function attachmentDescriptorForLedger(attachment) {
+  return {
+    id: attachment.id,
+    name: attachment.name,
+    mime_type: attachment.mime_type,
+    size_bytes: attachment.size_bytes,
+    sha256: attachment.sha256,
+    integrity_status: attachment.integrity_status || "verified",
+    staged_at: attachment.staged_at || null,
+    executor_handoff_status: attachment.executor_handoff_status || "pending",
+    delivered_at: attachment.delivered_at || null,
+    cleanup_status: attachment.cleanup_status || "pending",
+    cleaned_at: attachment.cleaned_at || null,
+    cleanup_error: attachment.cleanup_error || null,
+  };
+}
+
+export function markAttachmentsDelivered(attachments, occurredAt = new Date().toISOString()) {
+  for (const attachment of attachments || []) {
+    attachment.executor_handoff_status = "delivered";
+    attachment.delivered_at = occurredAt;
+  }
+}
+
+export function markAttachmentsCleaned(attachments, occurredAt = new Date().toISOString()) {
+  for (const attachment of attachments || []) {
+    if (attachment.storage === "source_path") continue;
+    attachment.cleanup_status = "cleaned";
+    attachment.cleaned_at = occurredAt;
+    attachment.cleanup_error = null;
+  }
+}
+
+export function markAttachmentsCleanupFailed(attachments, error) {
+  const message =
+    error instanceof Error ? error.message : String(error || "attachment cleanup failed");
+  for (const attachment of attachments || []) {
+    if (attachment.storage === "source_path") continue;
+    attachment.cleanup_status = "failed";
+    attachment.cleanup_error = message;
+  }
+}
+
+function safeAttachmentName(value) {
+  const name = String(value || "")
+    .normalize("NFKC")
+    .replace(/[\u0000-\u001f\u007f]/g, "")
+    .trim();
+  if (!name || name !== path.basename(name) || name === "." || name === "..") {
+    throw new Error("attachment has an invalid file name");
+  }
+  if (name.length > 180) throw new Error("attachment file name exceeds 180 characters");
+  return name;
+}
+
+function normalizeMimeType(value) {
+  return String(value || "application/octet-stream")
+    .split(";", 1)[0]
+    .trim()
+    .toLowerCase();
+}
+
+function isAllowedMimeType(value) {
+  return value.startsWith("text/") || ALLOWED_EXACT_MIME_TYPES.has(value);
+}
+
+function inferMimeType(value) {
+  const extension = path.extname(value).toLowerCase();
+  return (
+    {
+      ".gif": "image/gif",
+      ".jpeg": "image/jpeg",
+      ".jpg": "image/jpeg",
+      ".json": "application/json",
+      ".md": "text/markdown",
+      ".pdf": "application/pdf",
+      ".png": "image/png",
+      ".svg": "image/svg+xml",
+      ".txt": "text/plain",
+      ".webp": "image/webp",
+      ".yaml": "application/x-yaml",
+      ".yml": "application/x-yaml",
+      ".zip": "application/zip",
+    }[extension] || "application/octet-stream"
+  );
+}
+
+function verifyManifestEntry(value, actual) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    value.name !== actual.name ||
+    normalizeMimeType(value.mime_type) !== actual.mimeType ||
+    value.size_bytes !== actual.size ||
+    String(value.sha256 || "").toLowerCase() !== actual.sha256
+  ) {
+    throw new Error(`attachment integrity check failed for ${actual.name}`);
+  }
+}

package/src/orchestrator/contract.js

@@ -64,6 +64,7 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
               "include unrelated changes",
             ],
       proposal_id: cleanString(request.proposal_id) || null,
+      attachments: Array.isArray(request.attachments) ? request.attachments : [],
       risk,
       design_review: {
         required: risk.requires_design_review,

package/src/orchestrator/independent-audit.js

@@ -1,6 +1,16 @@
 import { bullets, cleanString, section } from "./shared.js";
 
 export function buildIndependentAuditInstruction(charter, attempt) {
+  const localEvidence = attempt.observed_evidence?.local || {};
+  const githubEvidence = attempt.observed_evidence?.github || {};
+  const evidenceArtifact = attempt.audit?.evidence_artifacts?.[0] || null;
+  const passingChecks = Array.isArray(githubEvidence.checks)
+    ? githubEvidence.checks
+        .filter((check) => check?.state === "success" || check?.conclusion === "SUCCESS")
+        .map((check) => cleanString(check.name))
+        .filter(Boolean)
+    : [];
+
   return [
     section(
       "role",
@@ -17,6 +27,21 @@ export function buildIndependentAuditInstruction(charter, attempt) {
         `Commit SHA: ${attempt.observed_evidence?.local?.head_sha || attempt.commit_sha || "unknown"}`,
       ].join("\n"),
     ),
+    section(
+      "verifiable_evidence",
+      [
+        `Local UI evidence path: ${attempt.ui_evidence_path || "not reported"}`,
+        `Local evidence verification: ${evidenceArtifact?.summary || "not available"}`,
+        `Reported tests:\n${bullets(attempt.tests_run || [])}`,
+        `Observed local branch: ${localEvidence.branch_name || "unknown"}`,
+        `Observed local HEAD: ${localEvidence.head_sha || "unknown"}`,
+        `Observed changed files:\n${bullets(localEvidence.changed_files || [])}`,
+        `Observed PR: ${githubEvidence.url || attempt.pr_url || "unknown"}`,
+        `Observed passing GitHub checks:\n${bullets(passingChecks)}`,
+        "The UI evidence is intentionally local-only and must not be committed. Inspect the reported path directly; do not fail it merely because screenshots are absent from the Git diff.",
+        "Treat reported commands and paths as leads, not proof. Verify the files, command-visible assertions, Git state, and relevant screenshots before accepting them.",
+      ].join("\n"),
+    ),
     section(
       "audit_scope",
       [

package/src/orchestrator/index.js

@@ -2,4 +2,4 @@ export { createCodingLoopSnapshot, newRunId } from "./contract.js";
 export { collectPrEvidence } from "./evidence.js";
 export { buildIndependentAuditInstruction } from "./independent-audit.js";
 export { recheckPrReadiness, runCodingLoop } from "./loop.js";
-export { parseStructuredMarker, parseStructuredResult } from "./result.js";
+export { mergeTokenUsage, parseStructuredMarker, parseStructuredResult } from "./result.js";

package/src/orchestrator/instruction.js

@@ -24,6 +24,21 @@ export function buildCodingInstruction(
     section("must_not", bullets(charter.must_not)),
   ];
 
+  if (charter.attachments?.length > 0) {
+    sections.push(
+      section(
+        "local_input_attachments",
+        [
+          "These read-only files were supplied by the user. Inspect them as part of the requirement. Do not move, rename, modify, or commit them.",
+          ...charter.attachments.map(
+            (attachment) =>
+              `- ${attachment.name} (${attachment.mime_type}, ${attachment.size_bytes} bytes, sha256 ${attachment.sha256}): ${attachment.local_path}`,
+          ),
+        ].join("\n"),
+      ),
+    );
+  }
+
   if (previousAttempt || previousFindings.length > 0) {
     sections.push(
       section(
@@ -77,7 +92,10 @@ export function buildCodingInstruction(
   return sections.join("\n\n");
 }
 
-export function buildPromptInterventions(charter, { attemptNumber, previousFindings }) {
+export function buildPromptInterventions(
+  charter,
+  { attemptNumber, previousFindings, humanGuidance = "" },
+) {
   const now = new Date().toISOString();
   const rows = [
     {
@@ -115,6 +133,14 @@ export function buildPromptInterventions(charter, { attemptNumber, previousFindi
       evidence_required: ["fixed_finding_codes", "rerun_report"],
     });
   }
+  if (humanGuidance.trim()) {
+    rows.push({
+      trigger: "human_guidance",
+      title: "Human guidance",
+      prompt: humanGuidance.trim(),
+      evidence_required: ["guidance_addressed"],
+    });
+  }
   return rows.map((row) => ({
     id: `${charter.id}-${row.trigger}-${attemptNumber}`,
     ...row,