@every-env/spiral-cli 0.1.0

package/src/config.ts

@@ -0,0 +1,49 @@
+// Local configuration store using `conf` package
+import Conf from "conf";
+
+// Draft stored locally (for tracking unsaved changes)
+export interface LocalDraft {
+  id: string;
+  sessionId: string;
+  title?: string;
+  localContent?: string; // Unsaved local changes
+  lastSyncedAt: string;
+}
+
+// Note item for scratchpad
+export interface NoteItem {
+  id: string;
+  content: string;
+  feedback?: string;
+  createdAt: string;
+}
+
+// User preferences
+export interface SpiralPreferences {
+  editor?: string; // Override $EDITOR
+  diffTool?: "inline" | "side-by-side";
+  toolCallVerbosity?: "minimal" | "normal" | "verbose";
+}
+
+// Main config schema
+export interface SpiralConfig {
+  currentWorkspaceId?: string;
+  currentStyleId?: string;
+  defaultModel?: string;
+  drafts: Record<string, LocalDraft>;
+  notes: NoteItem[];
+  preferences: SpiralPreferences;
+}
+
+// Initialize conf with defaults
+export const config = new Conf<SpiralConfig>({
+  projectName: "spiral-cli",
+  defaults: {
+    drafts: {},
+    notes: [],
+    preferences: {
+      diffTool: "inline",
+      toolCallVerbosity: "normal",
+    },
+  },
+});

package/src/drafts/editor.ts

@@ -0,0 +1,105 @@
+// $EDITOR integration with security mitigations
+// See plan: Security review identified command injection and temp file risks
+
+import { randomUUID } from "node:crypto";
+import { chmodSync, lstatSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+// SECURITY: Allowlist of safe editors
+const ALLOWED_EDITORS = new Set([
+  "vi",
+  "vim",
+  "nvim",
+  "nano",
+  "emacs",
+  "code",
+  "subl",
+  "atom",
+  "micro",
+  "helix",
+  "joe",
+  "pico",
+]);
+
+/**
+ * Get a secure editor command
+ * @security Validates against allowlist and rejects shell metacharacters
+ */
+function getSecureEditor(): string {
+  const rawEditor = process.env.EDITOR || process.env.VISUAL || "vi";
+  const firstPart = rawEditor.split(" ")[0] || "vi";
+  const editorName = basename(firstPart);
+
+  if (!ALLOWED_EDITORS.has(editorName)) {
+    console.warn(`Warning: $EDITOR '${rawEditor}' not in allowlist, using 'vi'`);
+    return "vi";
+  }
+
+  // SECURITY: Reject shell metacharacters
+  if (/[;&|`$]/.test(rawEditor)) {
+    throw new Error("$EDITOR contains shell metacharacters");
+  }
+
+  return rawEditor;
+}
+
+export interface EditorResult {
+  content: string;
+  changed: boolean;
+}
+
+/**
+ * Open content in $EDITOR for editing
+ * @security Uses secure temp paths, restrictive permissions, and secure cleanup
+ */
+export async function editInEditor(
+  initialContent: string,
+  options: { extension?: string; title?: string } = {},
+): Promise<EditorResult> {
+  const { extension = ".md" } = options;
+
+  // SECURITY: Unpredictable temp path
+  const tempPath = join(tmpdir(), `spiral-${randomUUID()}${extension}`);
+
+  try {
+    // SECURITY: Write with restrictive permissions (owner read/write only)
+    writeFileSync(tempPath, initialContent, { mode: 0o600 });
+    chmodSync(tempPath, 0o600);
+
+    const editor = getSecureEditor();
+
+    // Get mtime before edit for change detection
+    const statBefore = lstatSync(tempPath);
+    const mtimeBefore = statBefore.mtimeMs;
+
+    // Split editor command (handles "vim -O" style editors)
+    const editorParts = editor.split(" ");
+    const editorPath = editorParts[0] || "vi";
+    const editorArgs = [...editorParts.slice(1), tempPath];
+
+    // Use Bun.spawn with stdio inheritance for interactive editing
+    const proc = Bun.spawn([editorPath, ...editorArgs], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    await proc.exited;
+
+    // Fast change detection via mtime
+    const statAfter = lstatSync(tempPath);
+    const changed = statAfter.mtimeMs !== mtimeBefore;
+    const content = changed ? await Bun.file(tempPath).text() : initialContent;
+
+    return { content, changed };
+  } finally {
+    // SECURITY: Secure cleanup - overwrite before deletion
+    try {
+      const size = initialContent.length;
+      writeFileSync(tempPath, Buffer.alloc(size, 0));
+      unlinkSync(tempPath);
+    } catch {
+      /* best effort cleanup */
+    }
+  }
+}

package/src/drafts/index.ts

@@ -0,0 +1,208 @@
+// Draft management commands
+import chalk from "chalk";
+import ora from "ora";
+import {
+  fetchDraft,
+  fetchDraftVersions,
+  fetchSessionDrafts,
+  restoreDraftVersion,
+  updateDraft,
+} from "../api";
+import { theme } from "../theme";
+import { editInEditor } from "./editor";
+
+export interface DraftCommandOptions {
+  json?: boolean;
+  limit?: number;
+}
+
+/**
+ * List all drafts in a session
+ */
+export async function listDrafts(sessionId: string, options: DraftCommandOptions): Promise<void> {
+  const spinner = ora("Fetching drafts...").start();
+
+  try {
+    const drafts = await fetchSessionDrafts(sessionId);
+    spinner.succeed("Drafts loaded");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, drafts }));
+      return;
+    }
+
+    if (drafts.length === 0) {
+      console.log(theme.dim("No drafts in this session."));
+      return;
+    }
+
+    console.log(theme.heading("\nDrafts:\n"));
+    for (const draft of drafts) {
+      const preview = draft.content?.slice(0, 60) || "";
+      console.log(`${theme.dim(draft.id.slice(0, 8))} ${chalk.white(draft.title || "Untitled")}`);
+      console.log(`  ${theme.dim(preview)}${preview.length >= 60 ? "..." : ""}\n`);
+    }
+  } catch (error) {
+    spinner.fail("Failed to fetch drafts");
+    throw error;
+  }
+}
+
+/**
+ * View a single draft
+ */
+export async function viewDraft(
+  sessionId: string,
+  draftId: string,
+  options: DraftCommandOptions,
+): Promise<void> {
+  const spinner = ora("Loading draft...").start();
+
+  try {
+    const draft = await fetchDraft(sessionId, draftId);
+    spinner.succeed("Draft loaded");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, draft }));
+      return;
+    }
+
+    console.log(theme.heading(`\n${draft.title || "Untitled Draft"}\n`));
+    console.log(draft.content);
+    console.log(theme.dim(`\nID: ${draft.id}`));
+    console.log(theme.dim(`Updated: ${new Date(draft.updated_at).toLocaleString()}`));
+  } catch (error) {
+    spinner.fail("Failed to load draft");
+    throw error;
+  }
+}
+
+/**
+ * Edit a draft in $EDITOR
+ */
+export async function editDraft(
+  sessionId: string,
+  draftId: string,
+  options: DraftCommandOptions,
+): Promise<void> {
+  const spinner = ora("Loading draft for editing...").start();
+
+  try {
+    const draft = await fetchDraft(sessionId, draftId);
+    spinner.stop();
+
+    console.log(theme.info(`Opening ${draft.title || "draft"} in editor...\n`));
+
+    const { content, changed } = await editInEditor(draft.content, {
+      title: draft.title || "draft",
+      extension: ".md",
+    });
+
+    if (!changed) {
+      console.log(theme.dim("No changes made."));
+      return;
+    }
+
+    const saveSpinner = ora("Saving changes...").start();
+    const updated = await updateDraft(sessionId, draftId, content);
+    saveSpinner.succeed("Draft saved");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, draft: updated }));
+    }
+  } catch (error) {
+    spinner.fail("Failed to edit draft");
+    throw error;
+  }
+}
+
+/**
+ * Update draft content directly (agent-native, bypasses $EDITOR)
+ */
+export async function updateDraftContent(
+  sessionId: string,
+  draftId: string,
+  content: string,
+  options: DraftCommandOptions & { title?: string },
+): Promise<void> {
+  const spinner = ora("Updating draft...").start();
+
+  try {
+    const updated = await updateDraft(sessionId, draftId, content, options.title);
+    spinner.succeed("Draft updated");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, draft: updated }));
+    } else {
+      console.log(theme.success(`Updated draft ${draftId.slice(0, 8)}`));
+    }
+  } catch (error) {
+    spinner.fail("Failed to update draft");
+    throw error;
+  }
+}
+
+/**
+ * List version history for a draft
+ */
+export async function listVersions(
+  sessionId: string,
+  draftId: string,
+  options: DraftCommandOptions,
+): Promise<void> {
+  const spinner = ora("Fetching version history...").start();
+
+  try {
+    const versions = await fetchDraftVersions(sessionId, draftId);
+    spinner.succeed("Versions loaded");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, versions }));
+      return;
+    }
+
+    console.log(theme.heading(`\nVersion History (${versions.length} versions):\n`));
+
+    const limit = options.limit || 10;
+    for (const version of versions.slice(0, limit)) {
+      const date = new Date(version.created_at).toLocaleString();
+      const sizeKb = (version.content.length / 1024).toFixed(1);
+      const by = version.created_by === "llm" ? theme.assistant("AI") : theme.user("You");
+
+      console.log(`${theme.dim(version.id.slice(0, 8))} ${by} - ${date} (${sizeKb}kb)`);
+    }
+
+    if (versions.length > limit) {
+      console.log(theme.dim(`\n... and ${versions.length - limit} more`));
+    }
+  } catch (error) {
+    spinner.fail("Failed to fetch versions");
+    throw error;
+  }
+}
+
+/**
+ * Restore a draft to a specific version
+ */
+export async function restoreVersion(
+  sessionId: string,
+  draftId: string,
+  versionId: string,
+  options: DraftCommandOptions,
+): Promise<void> {
+  const spinner = ora("Restoring version...").start();
+
+  try {
+    const draft = await restoreDraftVersion(sessionId, draftId, versionId);
+    spinner.succeed("Version restored");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, draft }));
+    } else {
+      console.log(theme.success(`Restored to version ${versionId.slice(0, 8)}`));
+    }
+  } catch (error) {
+    spinner.fail("Failed to restore version");
+    throw error;
+  }
+}

package/src/notes/index.ts

@@ -0,0 +1,130 @@
+// Scratchpad/notes management with local persistence
+import { confirm } from "@inquirer/prompts";
+import chalk from "chalk";
+import { type NoteItem, config } from "../config";
+import { theme } from "../theme";
+
+export interface NoteCommandOptions {
+  json?: boolean;
+  force?: boolean;
+}
+
+/**
+ * Add a new note
+ */
+export function addNote(
+  content: string,
+  feedback?: string,
+  options: NoteCommandOptions = {},
+): void {
+  const notes = config.get("notes") || [];
+
+  const note: NoteItem = {
+    id: `note-${Date.now()}`,
+    content,
+    feedback,
+    createdAt: new Date().toISOString(),
+  };
+
+  notes.push(note);
+  config.set("notes", notes);
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, note }));
+  } else {
+    console.log(
+      theme.success(`Note added: "${content.slice(0, 40)}${content.length > 40 ? "..." : ""}"`),
+    );
+  }
+}
+
+/**
+ * List all notes
+ */
+export function listNotes(options: NoteCommandOptions): void {
+  const notes = config.get("notes") || [];
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, notes }));
+    return;
+  }
+
+  if (notes.length === 0) {
+    console.log(theme.dim("No notes. Use /note <text> to add one."));
+    return;
+  }
+
+  console.log(theme.heading(`\nNotes (${notes.length}):\n`));
+
+  for (const note of notes) {
+    const date = new Date(note.createdAt).toLocaleString();
+    console.log(`${theme.dim(note.id.slice(0, 12))} ${chalk.white(note.content)}`);
+    if (note.feedback) {
+      console.log(`  ${theme.info("Feedback:")} ${note.feedback}`);
+    }
+    console.log(`  ${theme.dim(date)}\n`);
+  }
+}
+
+/**
+ * Clear all notes
+ */
+export async function clearNotes(options: NoteCommandOptions): Promise<void> {
+  const notes = config.get("notes") || [];
+
+  if (notes.length === 0) {
+    console.log(theme.dim("No notes to clear."));
+    return;
+  }
+
+  if (!options.force && !options.json) {
+    const proceed = await confirm({
+      message: `Delete all ${notes.length} notes?`,
+      default: false,
+    });
+    if (!proceed) {
+      console.log(theme.dim("Cancelled."));
+      return;
+    }
+  }
+
+  config.set("notes", []);
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, cleared: notes.length }));
+  } else {
+    console.log(theme.success(`Cleared ${notes.length} notes.`));
+  }
+}
+
+/**
+ * Remove a specific note by ID
+ */
+export function removeNote(noteId: string, options: NoteCommandOptions): void {
+  const notes = config.get("notes") || [];
+  const index = notes.findIndex((n: NoteItem) => n.id === noteId || n.id.startsWith(noteId));
+
+  if (index === -1) {
+    throw new Error(`Note not found: ${noteId}`);
+  }
+
+  const [removed] = notes.splice(index, 1);
+  config.set("notes", notes);
+
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, removed }));
+  } else if (removed) {
+    console.log(theme.dim(`Removed note: "${removed.content.slice(0, 30)}..."`));
+  }
+}
+
+/**
+ * Get notes formatted for API submission
+ */
+export function getNotesForApi(): Array<{ content: string; feedback: string }> {
+  const notes = config.get("notes") || [];
+  return notes.map((n: NoteItem) => ({
+    content: n.content,
+    feedback: n.feedback || "",
+  }));
+}

package/src/styles/index.ts

@@ -0,0 +1,45 @@
+// Writing styles management
+import chalk from "chalk";
+import ora from "ora";
+import { fetchWritingStyles } from "../api";
+import { theme } from "../theme";
+
+export interface StyleCommandOptions {
+  json?: boolean;
+}
+
+/**
+ * List all available writing styles
+ */
+export async function listStyles(options: StyleCommandOptions): Promise<void> {
+  const spinner = ora("Fetching writing styles...").start();
+
+  try {
+    const styles = await fetchWritingStyles();
+    spinner.succeed("Styles loaded");
+
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, styles }));
+      return;
+    }
+
+    if (styles.length === 0) {
+      console.log(theme.dim("No writing styles found. Create one in the web app."));
+      return;
+    }
+
+    console.log(theme.heading("\nWriting Styles:\n"));
+    for (const style of styles) {
+      console.log(`${theme.dim(style.id.slice(0, 8))} ${chalk.white(style.name)}`);
+      if (style.description) {
+        console.log(
+          `  ${theme.dim(style.description.slice(0, 80))}${style.description.length > 80 ? "..." : ""}`,
+        );
+      }
+      console.log();
+    }
+  } catch (error) {
+    spinner.fail("Failed to fetch styles");
+    throw error;
+  }
+}

package/src/suggestions/diff.ts

@@ -0,0 +1,33 @@
+// Diff display utilities
+import chalk from "chalk";
+import { theme } from "../theme";
+
+/**
+ * Display inline diff (before/after stacked)
+ */
+export function displayInlineDiff(before: string, after: string): void {
+  console.log(theme.heading("\n--- Before ---"));
+  console.log(chalk.red(before));
+  console.log(theme.heading("\n--- After ---"));
+  console.log(chalk.green(after));
+  console.log();
+}
+
+/**
+ * Display side-by-side diff
+ */
+export function displaySideBySideDiff(before: string, after: string, width = 40): void {
+  const beforeLines = before.split("\n");
+  const afterLines = after.split("\n");
+  const maxLines = Math.max(beforeLines.length, afterLines.length);
+
+  console.log(theme.heading(`\n${"Before".padEnd(width)} | After`));
+  console.log(`${"-".repeat(width)} | ${"-".repeat(width)}`);
+
+  for (let i = 0; i < maxLines; i++) {
+    const b = (beforeLines[i] || "").slice(0, width).padEnd(width);
+    const a = (afterLines[i] || "").slice(0, width);
+    console.log(`${chalk.red(b)} | ${chalk.green(a)}`);
+  }
+  console.log();
+}