@picoai/tickets 0.5.0 → 0.5.5

package/.tickets/spec/AGENTS_EXAMPLE.md

@@ -16,6 +16,8 @@ The purpose of this bootstrap is to ensure an agent loads the canonical ticketin
 - Record `completion` metadata every time a ticket is moved to `done`.
 - When a human overrides incomplete completion gates, record that override in the ticket via `npx @picoai/tickets status --status done --acceptance-criteria ... --verification-state ... --override-by ... --override-reason ...`.
 - When logging via the CLI: use `npx @picoai/tickets log --machine` so logs are strictly structured.
+- If the human asks to remove the tickets workflow from this repo, run `npx @picoai/tickets uninstall`.
+- Use `npx @picoai/tickets uninstall --all` only when the human explicitly asks to delete ticket directories and logs too.
 - Respect `assignment.mode`, `agent_limits`, active advisory claims, and repo-local defaults in `.tickets/config.yml`.
 
 ### Bootstrapping TICKETS.md

package/README.md

@@ -114,6 +114,17 @@ npx @picoai/tickets init [--examples] [--apply]
 - `--examples`: generate example tickets and logs that validate under the current spec
 - `--apply`: refresh managed `TICKETS.md`, the managed `AGENTS.md` workflow block, and repo skill content
 
+### `uninstall`
+
+```bash
+npx @picoai/tickets uninstall [--all] [--yes]
+```
+
+- default: remove tickets-managed workflow files while keeping ticket directories and logs under `/.tickets/<ticket-id>/`
+- `--all`: also remove ticket directories and logs for a clean reset
+- `--yes`: skip interactive confirmation prompts
+- does not remove `@picoai/tickets` from `package.json` (run your package manager uninstall command separately)
+
 ### `new`
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picoai/tickets",
-  "version": "0.5.0",
+  "version": "0.5.5",
   "description": "Repo-native ticketing CLI and assets for Markdown-first, append-only ticket workflows.",
   "license": "Apache-2.0",
   "type": "module",

package/release-history.json

@@ -28,6 +28,13 @@
       "date": "2026-03-17",
       "channel": "latest",
       "notes": "Published to npm"
+    },
+    {
+      "version": "0.5.0",
+      "commit": "66691ef",
+      "date": "2026-03-17",
+      "channel": "latest",
+      "notes": "Published to npm"
     }
   ]
 }

package/src/cli.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import readline from "node:readline/promises";
 
 import { Command } from "commander";
 import yaml from "yaml";
@@ -806,6 +807,273 @@ function upsertAgentsSection(existingContent, templateContent) {
   return replaceHeadingBlock(withoutLegacyMarkers, managedBlock, AGENTS_SECTION_HEADING, 2);
 }
 
+function removeHeadingBlock(content, headingText, headingLevel) {
+  const lines = normalizeContent(content).split("\n");
+  const range = findHeadingBlockRange(lines, headingText, headingLevel);
+  if (!range) {
+    return [normalizeContent(content), false];
+  }
+
+  const before = lines.slice(0, range.start).join("\n").trimEnd();
+  const after = lines.slice(range.end).join("\n").trimStart();
+  if (!before && !after) {
+    return ["", true];
+  }
+  if (!before) {
+    return [after, true];
+  }
+  if (!after) {
+    return [before, true];
+  }
+  return [`${before}\n\n${after}`, true];
+}
+
+function removeHeadingBlocks(content, headingText, headingLevel) {
+  let next = normalizeContent(content);
+  let removed = false;
+  while (true) {
+    const [updated, didRemove] = removeHeadingBlock(next, headingText, headingLevel);
+    if (!didRemove) {
+      break;
+    }
+    removed = true;
+    next = updated;
+  }
+  return [next, removed];
+}
+
+function detectPriorInitState(root) {
+  const ticketsMdPath = path.join(root, "TICKETS.md");
+  const ticketsRoot = path.join(root, ".tickets");
+  const repoConfig = path.join(ticketsRoot, "config.yml");
+  const repoSkill = path.join(ticketsRoot, "skills", "tickets", "SKILL.md");
+  const currentSpec = path.join(root, BASE_DIR, FORMAT_VERSION_URL);
+  const hadArtifacts =
+    fs.existsSync(ticketsMdPath) || fs.existsSync(repoConfig) || fs.existsSync(repoSkill) || fs.existsSync(currentSpec);
+
+  if (!hadArtifacts) {
+    return null;
+  }
+
+  if (fs.existsSync(ticketsMdPath)) {
+    try {
+      const content = fs.readFileSync(ticketsMdPath, "utf8");
+      const versionMatch = content.match(/^\s*-\s*written_by:\s*@picoai\/tickets@([^\s]+)\s*$/m);
+      if (versionMatch?.[1] === TOOL_VERSION) {
+        return "same";
+      }
+    } catch {
+      // Best-effort heuristic only.
+    }
+  }
+
+  if (fs.existsSync(currentSpec)) {
+    return "same";
+  }
+
+  return "outdated";
+}
+
+function toPosixPath(value) {
+  return String(value).replaceAll(path.sep, "/");
+}
+
+function displayRelativePath(root, targetPath, isDir = false) {
+  const relative = path.relative(root, targetPath);
+  const base = relative ? toPosixPath(relative) : ".";
+  if (isDir && !base.endsWith("/")) {
+    return `${base}/`;
+  }
+  return base;
+}
+
+function removePathWithLog(root, targetPath) {
+  if (!fs.existsSync(targetPath)) {
+    return false;
+  }
+  const stat = fs.lstatSync(targetPath);
+  fs.rmSync(targetPath, { recursive: true, force: true });
+  process.stdout.write(`Removed ${displayRelativePath(root, targetPath, stat.isDirectory())}\n`);
+  return true;
+}
+
+function removeTicketingWorkflowFromAgents(root) {
+  const agentsMdPath = path.join(root, "AGENTS.md");
+  if (!fs.existsSync(agentsMdPath)) {
+    return;
+  }
+
+  const existing = fs.readFileSync(agentsMdPath, "utf8");
+  let next = stripManagedSection(existing, AGENTS_LEGACY_SECTION_START, AGENTS_LEGACY_SECTION_END);
+  let removed = next !== normalizeContent(existing);
+
+  let removedByHeading;
+  [next, removedByHeading] = removeHeadingBlocks(next, AGENTS_SECTION_HEADING, 2);
+  removed ||= removedByHeading;
+  [next, removedByHeading] = removeHeadingBlocks(next, AGENTS_SECTION_HEADING, 1);
+  removed ||= removedByHeading;
+
+  const normalizedNext = normalizeContent(next).trim();
+  if (!removed) {
+    return;
+  }
+
+  if (!normalizedNext) {
+    fs.rmSync(agentsMdPath, { force: true });
+    process.stdout.write("Removed AGENTS.md\n");
+    return;
+  }
+
+  fs.writeFileSync(agentsMdPath, `${normalizedNext}\n`);
+  process.stdout.write("Removed Ticketing Workflow section from AGENTS.md\n");
+}
+
+function keepOnlyTicketDirectories(root) {
+  const ticketsRoot = path.join(root, ".tickets");
+  if (!fs.existsSync(ticketsRoot) || !fs.statSync(ticketsRoot).isDirectory()) {
+    return;
+  }
+
+  const entries = fs.readdirSync(ticketsRoot, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(ticketsRoot, entry.name);
+    if (entry.isDirectory() && fs.existsSync(path.join(entryPath, "ticket.md"))) {
+      continue;
+    }
+    removePathWithLog(root, entryPath);
+  }
+
+  const remaining = fs.readdirSync(ticketsRoot, { withFileTypes: true });
+  if (remaining.length === 0) {
+    fs.rmSync(ticketsRoot, { force: true });
+    process.stdout.write("Removed .tickets/\n");
+  }
+}
+
+function removeTicketsManagedFiles(root, removeAllTickets) {
+  removePathWithLog(root, path.join(root, "TICKETS.md"));
+  removeTicketingWorkflowFromAgents(root);
+  removePathWithLog(root, path.join(root, "AGENTS_EXAMPLE.md"));
+  removePathWithLog(root, path.join(root, "TICKETS.override.md"));
+
+  if (removeAllTickets) {
+    removePathWithLog(root, path.join(root, ".tickets"));
+  } else {
+    keepOnlyTicketDirectories(root);
+  }
+}
+
+async function promptYesNo(ask, prompt) {
+  while (true) {
+    const answer = (await ask(prompt)).trim().toLowerCase();
+    if (!answer) {
+      return false;
+    }
+    if (["y", "yes"].includes(answer)) {
+      return true;
+    }
+    if (["n", "no"].includes(answer)) {
+      return false;
+    }
+    process.stdout.write("Please enter y or n.\n");
+  }
+}
+
+async function resolveUninstallScope(options) {
+  if (options.yes) {
+    return options.all ? "all" : "keep";
+  }
+
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      if (options.all) {
+        const confirmed = await promptYesNo(
+          (prompt) => rl.question(prompt),
+          "This operation is destructive and will remove all files created by @picoai/tickets from this repository. This action cannot be undone.\n\nProceed? [y/N]:",
+        );
+        if (!confirmed) {
+          process.stdout.write("Canceled. No changes made.\n");
+          return null;
+        }
+        return "all";
+      }
+
+      const proceed = await promptYesNo(
+        (prompt) => rl.question(prompt),
+        "This operation is destructive and will remove files created by @picoai/tickets from this repository. It will keep ticket directories and logs under .tickets/<ticket-id>/ by default. This action cannot be undone.\n\nProceed? [y/N]:",
+      );
+      if (!proceed) {
+        process.stdout.write("Canceled. No changes made.\n");
+        return null;
+      }
+
+      const deleteTickets = await promptYesNo(
+        (prompt) => rl.question(prompt),
+        "Remove all ticket directories and logs as well? [y/N]:",
+      );
+      return deleteTickets ? "all" : "keep";
+    } finally {
+      rl.close();
+    }
+  }
+
+  const answers = fs.readFileSync(0, "utf8").split(/\r?\n/);
+  let cursor = 0;
+  const askFromBuffer = async (prompt) => {
+    process.stdout.write(prompt);
+    if (cursor >= answers.length) {
+      return "";
+    }
+    const value = answers[cursor];
+    cursor += 1;
+    return value ?? "";
+  };
+
+  if (options.all) {
+    const confirmed = await promptYesNo(
+      askFromBuffer,
+      "This operation is destructive and will remove all files created by @picoai/tickets from this repository. This action cannot be undone.\n\nProceed? [y/N]:",
+    );
+    if (!confirmed) {
+      process.stdout.write("Canceled. No changes made.\n");
+      return null;
+    }
+    return "all";
+  }
+
+  const proceed = await promptYesNo(
+    askFromBuffer,
+    "This operation is destructive and will remove files created by @picoai/tickets from this repository. It will keep ticket directories and logs under .tickets/<ticket-id>/ by default. This action cannot be undone.\n\nProceed? [y/N]:",
+  );
+  if (!proceed) {
+    process.stdout.write("Canceled. No changes made.\n");
+    return null;
+  }
+
+  const deleteTickets = await promptYesNo(askFromBuffer, "Remove all ticket directories and logs as well? [y/N]:");
+  return deleteTickets ? "all" : "keep";
+}
+
+async function cmdUninstall(options) {
+  const scope = await resolveUninstallScope(options);
+  if (!scope) {
+    return 0;
+  }
+
+  if (scope === "all") {
+    process.stdout.write("Removing all files created by @picoai/tickets from this repository.\n");
+    removeTicketsManagedFiles(repoRoot(), true);
+    return 0;
+  }
+
+  process.stdout.write(
+    "Removing all files created by @picoai/tickets from this repository except for ticket directories and logs.\n",
+  );
+  removeTicketsManagedFiles(repoRoot(), false);
+  return 0;
+}
+
 function applyAgentsMdSection(root, templateContent) {
   const agentsMdPath = path.join(root, "AGENTS.md");
   const existing = fs.existsSync(agentsMdPath) ? fs.readFileSync(agentsMdPath, "utf8") : "";
@@ -1130,8 +1398,9 @@ function generateExampleTickets() {
 }
 
 async function cmdInit(options) {
-  ensureDir(ticketsDir());
   const root = repoRoot();
+  const priorInitState = detectPriorInitState(root);
+  ensureDir(ticketsDir());
   const repoBaseDir = path.join(root, BASE_DIR);
   ensureDir(repoBaseDir);
   const apply = Boolean(options.apply);
@@ -1178,7 +1447,13 @@ async function cmdInit(options) {
   }
 
   invalidatePlanningIndex();
-  process.stdout.write("Initialized.\n");
+  if (!apply && priorInitState === null) {
+    process.stdout.write("Repo successfully initialized; run init --apply to directly update agents.md if desired.\n");
+  } else if (!apply && priorInitState === "outdated") {
+    process.stdout.write("Repo previously initialized, but may be outdated; run init --apply to update\n");
+  } else if (!apply && priorInitState === "same") {
+    process.stdout.write("Repo already initialized with this version; run init --apply to apply updates anyway\n");
+  }
   return 0;
 }
 
@@ -2136,6 +2411,18 @@ export async function run(argv = process.argv.slice(2)) {
       });
     });
 
+  program
+    .command("uninstall")
+    .description("Remove @picoai/tickets managed files from this repository")
+    .option("--all", "Also remove ticket directories and logs under .tickets/")
+    .option("--yes", "Run non-interactively with confirmation accepted")
+    .action(async (options) => {
+      process.exitCode = await cmdUninstall({
+        all: Boolean(options.all),
+        yes: Boolean(options.yes),
+      });
+    });
+
   try {
     await program.parseAsync(argv, { from: "user" });
   } catch (error) {

package/src/lib/projections.js

@@ -37,6 +37,8 @@ export function renderRepoSkill(profile = loadDefaultProfile()) {
     "- Record `completion` metadata every time a ticket is moved to `done`.",
     "- When a human overrides incomplete completion gates, record the exception through `npx @picoai/tickets status --status done --acceptance-criteria ... --verification-state ... --override-by ... --override-reason ...` so `ticket.md` and the status log both reflect it.",
     "- Use `npx @picoai/tickets status`, `log`, `claim`, `plan`, and `graph` instead of editing derived state manually.",
+    "- If a human asks to remove the tickets workflow from the repo, run `npx @picoai/tickets uninstall`.",
+    "- Use `npx @picoai/tickets uninstall --all` only when the human explicitly asks to delete ticket directories and logs too.",
     "- When humans use terms like feature, phase, milestone, roadmap, or repo-specific equivalents, translate them through `.tickets/config.yml` and then call the generic CLI fields.",
     "- Respect repo overrides in `.tickets/config.yml` and any narrative guidance in `TICKETS.override.md` if present.",
     "",