@danypops/tickets 0.8.7 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.8.7",
+  "version": "0.9.0",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "@danypops/vehicle-core": "^0.12.3",
     "@danypops/vehicle-server": "^0.17.1",
     "@danypops/vehicle-client": "^0.5.0",
-    "@danypops/enigma-client": "^0.3.0",
+    "@danypops/enigma-client": "^0.6.1",
     "@gitbeaker/rest": "^43.8.0",
     "commander": "^12.1.0",
     "jira.js": "^5.4.0",

package/src/agent-tools/tickets-vehicle.ts

@@ -236,6 +236,51 @@ const OPERATIONS: readonly OperationSpec[] = [
     properties: { name: stringProp, limit: numberProp },
     required: ["name"],
   },
+  {
+    action: "stage.add",
+    description:
+      "Stages a create/update/comment payload locally for review -- no live backend call. Free: never gated by the approval requirement stage.push carries.",
+    effect: "local-write",
+    properties: { payload: { type: "object" } },
+    required: ["payload"],
+  },
+  {
+    action: "stage.list",
+    description: "Lists every currently staged (not yet pushed) payload.",
+    effect: "read",
+    properties: {},
+    required: [],
+  },
+  {
+    action: "stage.show",
+    description: "Shows one staged payload by id.",
+    effect: "read",
+    properties: { id: stringProp },
+    required: ["id"],
+  },
+  {
+    action: "stage.patch",
+    description:
+      "Edits a staged payload's text fields in place before pushing it -- e.g. fixing a field that would otherwise fail backend validation.",
+    effect: "local-write",
+    properties: { id: stringProp, fields: { type: "object" } },
+    required: ["id", "fields"],
+  },
+  {
+    action: "stage.drop",
+    description: "Discards a staged payload without ever sending it to a live backend.",
+    effect: "local-write",
+    properties: { id: stringProp },
+    required: ["id"],
+  },
+  {
+    action: "stage.push",
+    description:
+      "Commits a staged payload to its live backend (create, update, or comment) -- a real, externally visible write, gated the same as issue.create/issue.update/issue.comment_add.",
+    effect: "external-write",
+    properties: { id: stringProp },
+    required: ["id"],
+  },
 ];
 
 /**
@@ -301,6 +346,13 @@ export function createTicketsVehicleRegistry(deps: Omit<TicketsAppDeps, "vehicle
   });
   // Every handler passes through the reviewed mapper above; unmatched failures stay redacted.
   registry.setExposeHandlerFailureDetails(true);
+  // Drafting (stage.add/list/show/patch/drop) stays local-write/read -- free,
+  // never gated. Committing a write to a live backend -- issue.create,
+  // issue.update, issue.comment_add, or stage.push landing a staged payload --
+  // is external-write, and this is what actually turns the gate on for that
+  // effect: registerVehicleTools' own ctx.ui.confirm() dance (see @danypops/vehicle-client-pi)
+  // then requires a real human decision before any of those four run.
+  registry.configureApprovals({ requireApprovalForEffects: ["destructive", "open-world", "external-write"] });
   for (const spec of OPERATIONS) {
     const operation = defineVehicleOperation({
       name: spec.action,

package/src/cli/index.ts

@@ -15,6 +15,7 @@ import { promptMaskedSecret } from "../auth/masked-prompt.js";
 import { deleteToken, isTokenFresh, listStoredBackends, loadToken, saveToken } from "../auth/token-store.js";
 import type { CreateInput, ListFilter, Priority, Status, UpdateInput } from "../issue/issue.js";
 import { parseStatus } from "../issue/issue.js";
+import type { StagePatchFields, StagePayload } from "../stage/store.js";
 import { installTicketsService, systemctlTickets, systemdUnitPath } from "./systemd-service.js";
 import { createTicketsClient, type TicketsRpcClient } from "./tickets-client.js";
 
@@ -299,6 +300,133 @@ discoverCmd
     );
   });
 
+function definedEntriesOnly<T extends Record<string, unknown>>(input: T): Partial<T> {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined)) as Partial<T>;
+}
+
+function buildStagePayload(opts: {
+  kind?: string;
+  backend?: string;
+  ref?: string;
+  title?: string;
+  description?: string;
+  status?: string;
+  priority?: Priority;
+  label?: string[];
+  assignee?: string;
+  project?: string;
+  body?: string;
+}): StagePayload {
+  if (opts.kind === "create") {
+    if (!opts.backend) throw new Error("stage add --kind create requires --backend");
+    if (!opts.title) throw new Error("stage add --kind create requires --title");
+    const input: CreateInput = definedEntriesOnly({
+      title: opts.title,
+      description: opts.description,
+      priority: opts.priority,
+      labels: opts.label,
+      assignee: opts.assignee,
+      project: opts.project,
+    }) as CreateInput;
+    return { kind: "create", backend: opts.backend, input };
+  }
+  if (opts.kind === "update") {
+    if (!opts.ref) throw new Error("stage add --kind update requires --ref");
+    const input: UpdateInput = definedEntriesOnly({
+      title: opts.title,
+      description: opts.description,
+      status: opts.status ? parseStatus(opts.status) : undefined,
+      priority: opts.priority,
+      labels: opts.label,
+      assignee: opts.assignee,
+    });
+    return { kind: "update", ref: opts.ref, input };
+  }
+  if (opts.kind === "comment") {
+    if (!opts.ref) throw new Error("stage add --kind comment requires --ref");
+    if (!opts.body) throw new Error("stage add --kind comment requires --body");
+    return { kind: "comment", ref: opts.ref, body: opts.body };
+  }
+  throw new Error(`stage add: unsupported --kind "${opts.kind}" (expected create, update, or comment)`);
+}
+
+const stage = program
+  .command("stage")
+  .description(
+    "stage a create/update/comment payload locally for review -- free, no live backend call. Committing it (stage push) requires approval, same as issue create/update/comment add.",
+  );
+
+stage
+  .command("add")
+  .description("stage a new create, update, or comment payload")
+  .requiredOption("--kind <kind>", "create | update | comment")
+  .option("-b, --backend <name>", "backend name (kind=create)")
+  .option("--ref <ref>", "target issue ref (kind=update|comment)")
+  .option("--title <text>", "title (kind=create|update)")
+  .option("--description <text>", "description (kind=create|update)")
+  .option("--status <status>", "new status (kind=update)")
+  .option("--priority <priority>", "priority: none|urgent|high|medium|low (kind=create|update)")
+  .option("--label <label...>", "label(s) (kind=create|update)")
+  .option("--assignee <user>", "assignee (kind=create|update)")
+  .option("--project <project>", "project key/id (kind=create)")
+  .option("--body <text>", "comment body (kind=comment)")
+  .action(async (opts) => {
+    await withClient((client) => client.call("stage.add", { payload: buildStagePayload(opts) }));
+  });
+
+stage
+  .command("list")
+  .description("list every currently staged payload")
+  .action(async () => {
+    await withClient((client) => client.call("stage.list", {}));
+  });
+
+stage
+  .command("show <id>")
+  .description("show one staged payload by id")
+  .action(async (id: string) => {
+    await withClient((client) => client.call("stage.show", { id }));
+  });
+
+stage
+  .command("patch <id>")
+  .description(
+    "edit a staged payload's text fields in place before pushing it -- e.g. fixing a field that would otherwise fail backend validation",
+  )
+  .option("--title <text>", "new title (create/update payloads)")
+  .option("--description <text>", "new description (create/update payloads)")
+  .option("--status <status>", "new status (update payloads)")
+  .option("--priority <priority>", "new priority (create/update payloads)")
+  .option("--label <label...>", "replace labels (create/update payloads)")
+  .option("--assignee <user>", "new assignee (create/update payloads)")
+  .option("--body <text>", "new comment body (comment payloads)")
+  .action(async (id: string, opts) => {
+    const fields: StagePatchFields = definedEntriesOnly({
+      title: opts.title,
+      description: opts.description,
+      status: opts.status ? parseStatus(opts.status) : undefined,
+      priority: opts.priority,
+      labels: opts.label,
+      assignee: opts.assignee,
+      body: opts.body,
+    });
+    await withClient((client) => client.call("stage.patch", { id, fields }));
+  });
+
+stage
+  .command("drop <id>")
+  .description("discard a staged payload without ever sending it to a live backend")
+  .action(async (id: string) => {
+    await withClient((client) => client.call("stage.drop", { id }));
+  });
+
+stage
+  .command("push <id>")
+  .description("commit a staged payload to its live backend -- requires approval, same as issue create/update/comment add")
+  .action(async (id: string) => {
+    await withClient((client) => client.call("stage.push", { id }));
+  });
+
 const daemon = program.command("daemon").description("manage the tickets daemon process");
 
 daemon

package/src/process/bootstrap.ts

@@ -19,6 +19,7 @@ import { buildApp, type TicketsAppDeps } from "../rpc/server.js";
 import { FOCUS_MIGRATIONS, FocusStore } from "../sqlite/focus.js";
 import { LEDGER_MIGRATIONS, Ledger } from "../sqlite/ledger.js";
 import { SAVED_QUERY_MIGRATIONS, SavedQueryStore } from "../sqlite/saved-queries.js";
+import { StageStore } from "../stage/store.js";
 import { createSyncTask } from "./poller.js";
 
 export interface BootstrapOptions {
@@ -52,6 +53,7 @@ export interface BootstrappedDaemon {
   ledger: Ledger;
   focusStore: FocusStore;
   queries: SavedQueryStore;
+  stageStore: StageStore;
   service: TicketService;
   options: StartDaemonOptions;
 }
@@ -67,6 +69,7 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
   const ledger = new Ledger(db);
   const focusStore = new FocusStore(db);
   const queries = new SavedQueryStore(db);
+  const stageStore = new StageStore();
   const logger = opts.logger ?? createLogger("tickets-daemon", { levelEnvVar: "TICKETS_LOG_LEVEL" });
   const config = opts.config ?? loadConfig();
   const buildRepos = opts.buildRepositories ?? buildRepositories;
@@ -84,6 +87,7 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     ledger,
     focusStore,
     queries,
+    stageStore,
     token,
     version,
     logger,
@@ -122,6 +126,7 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
         ledger,
         focusStore,
         queries,
+        stageStore,
         token,
         version,
         logger,
@@ -133,5 +138,5 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     },
   };
 
-  return { db, ledger, focusStore, queries, service, options };
+  return { db, ledger, focusStore, queries, stageStore, service, options };
 }

package/src/rpc/error-status.ts

@@ -2,10 +2,12 @@ import { AuthRequiredError, IssueNotFoundError } from "../issue/errors.js";
 import { NotSupportedError, UnknownBackendError } from "../issue/service.js";
 import { FocusError } from "../sqlite/focus.js";
 import { SavedQueryNotFoundError } from "../sqlite/saved-queries.js";
+import { StagedItemNotFoundError } from "../stage/store.js";
 
 /** Returns the legacy HTTP status only for reviewed business errors; unknown failures stay unclassified. */
 export function statusForKnownTicketError(error: unknown): number | undefined {
-  if (error instanceof IssueNotFoundError || error instanceof SavedQueryNotFoundError) return 404;
+  if (error instanceof IssueNotFoundError || error instanceof SavedQueryNotFoundError || error instanceof StagedItemNotFoundError)
+    return 404;
   if (error instanceof UnknownBackendError || error instanceof NotSupportedError || error instanceof FocusError) return 400;
   if (error instanceof AuthRequiredError) return 422;
   return undefined;

package/src/rpc/ops.ts

@@ -8,6 +8,7 @@ import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../is
 import type { Template } from "../issue/template.js";
 import type { TicketFocusState } from "../sqlite/focus.js";
 import type { SavedQuery } from "../sqlite/saved-queries.js";
+import type { StagedItem, StagePatchFields, StagePayload } from "../stage/store.js";
 
 export type TicketOperation =
   | "backends.list"
@@ -35,6 +36,12 @@ export type TicketOperation =
   | "query.list"
   | "query.remove"
   | "query.run"
+  | "stage.add"
+  | "stage.list"
+  | "stage.show"
+  | "stage.patch"
+  | "stage.drop"
+  | "stage.push"
   | "daemon.shutdown";
 
 export interface TicketOpInputs extends Record<TicketOperation, unknown> {
@@ -63,9 +70,18 @@ export interface TicketOpInputs extends Record<TicketOperation, unknown> {
   "query.list": Record<string, never>;
   "query.remove": { name: string };
   "query.run": { name: string; limit?: number };
+  "stage.add": { payload: StagePayload };
+  "stage.list": Record<string, never>;
+  "stage.show": { id: string };
+  "stage.patch": { id: string; fields: StagePatchFields };
+  "stage.drop": { id: string };
+  "stage.push": { id: string };
   "daemon.shutdown": Record<string, never>;
 }
 
+/** stage.push's own output shape -- whichever real op the staged payload's kind maps to (issue.create/issue.update/issue.comment_add). */
+export type StagePushResult = { issue: Issue } | { comment: Comment };
+
 export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
   "backends.list": { backends: { name: string; supportsRawQuery: boolean }[] };
   "issue.list": { issues: Issue[] };
@@ -92,6 +108,12 @@ export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
   "query.list": { queries: SavedQuery[] };
   "query.remove": { removed: boolean };
   "query.run": { issues: Issue[] };
+  "stage.add": { item: StagedItem };
+  "stage.list": { items: StagedItem[] };
+  "stage.show": { item: StagedItem };
+  "stage.patch": { item: StagedItem };
+  "stage.drop": { dropped: boolean };
+  "stage.push": { result: StagePushResult };
   "daemon.shutdown": { stopping: true };
 }
 
@@ -121,6 +143,12 @@ export const TICKET_OPERATIONS: TicketOperation[] = [
   "query.list",
   "query.remove",
   "query.run",
+  "stage.add",
+  "stage.list",
+  "stage.show",
+  "stage.patch",
+  "stage.drop",
+  "stage.push",
   "daemon.shutdown",
 ];
 

package/src/rpc/server.ts

@@ -16,8 +16,9 @@ import type { TicketService } from "../issue/service.js";
 import { FocusError, type FocusStore } from "../sqlite/focus.js";
 import type { Ledger } from "../sqlite/ledger.js";
 import { SavedQueryNotFoundError, type SavedQueryStore } from "../sqlite/saved-queries.js";
+import type { StagePayload, StageStore } from "../stage/store.js";
 import { statusForKnownTicketError } from "./error-status.js";
-import { TICKET_OPERATIONS, type TicketOperation, type TicketOpInputs, type TicketOpOutputs } from "./ops.js";
+import { type StagePushResult, TICKET_OPERATIONS, type TicketOperation, type TicketOpInputs, type TicketOpOutputs } from "./ops.js";
 
 export interface TicketsAppDeps {
   service: TicketService;
@@ -43,6 +44,7 @@ export interface TicketsAppDeps {
    * from this file).
    */
   vehicleRegistry: VehicleRegistry;
+  stageStore: StageStore;
 }
 
 // Narrower than TicketsAppDeps on purpose: no real handler reads
@@ -104,6 +106,20 @@ export const TICKET_OP_HANDLERS: { [Op in TicketOperation]: Handler<Op> } = {
     if (!saved) throw new SavedQueryNotFoundError(input.name);
     return { issues: await deps.service.runQuery(saved.backend, saved.query, input.limit) };
   },
+  "stage.add": async (deps, input) => ({ item: deps.stageStore.add(input.payload) }),
+  "stage.list": async (deps) => ({ items: deps.stageStore.list() }),
+  "stage.show": async (deps, input) => ({ item: deps.stageStore.show(input.id) }),
+  "stage.patch": async (deps, input) => ({ item: deps.stageStore.patch(input.id, input.fields) }),
+  "stage.drop": async (deps, input) => ({ dropped: deps.stageStore.drop(input.id) }),
+  "stage.push": async (deps, input) => {
+    // Left staged (not dropped) on a live-write failure -- e.g. a field that
+    // failed backend validation -- so it can be patched and retried, per
+    // this feature's own emcee-ported motivation.
+    const item = deps.stageStore.show(input.id);
+    const result = await pushStagedPayload(deps, item.payload);
+    deps.stageStore.drop(item.id);
+    return { result };
+  },
   "daemon.shutdown": async (deps) => {
     // Deferred so this handler's own response has already been handed back
     // to Bun.serve before the process starts tearing down.
@@ -112,6 +128,22 @@ export const TICKET_OP_HANDLERS: { [Op in TicketOperation]: Handler<Op> } = {
   },
 };
 
+/** stage.push's real dispatch: whichever live op a staged payload's kind maps to, never reimplemented -- same TicketService methods issue.create/issue.update/issue.comment_add already call. */
+async function pushStagedPayload(deps: Omit<TicketsAppDeps, "vehicleRegistry">, payload: StagePayload): Promise<StagePushResult> {
+  switch (payload.kind) {
+    case "create":
+      return { issue: await deps.service.create(payload.backend, payload.input) };
+    case "update":
+      return { issue: await deps.service.update(payload.ref, payload.input) };
+    case "comment":
+      return { comment: await deps.service.addComment(payload.ref, payload.body) };
+    default: {
+      const _exhaustive: never = payload;
+      throw new Error(`unhandled staged payload kind: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+
 function isTicketOperation(value: unknown): value is TicketOperation {
   return typeof value === "string" && (TICKET_OPERATIONS as string[]).includes(value);
 }

package/src/stage/store.ts

@@ -0,0 +1,122 @@
+/**
+ * Staging — a pre-submission cache for any textual write (a new issue, an
+ * update, a comment) so it can be reviewed and edited before it ever touches
+ * a live backend. Ported from `~/Workspace/emcee`'s working stage
+ * capability, generalized from issue-creation-only to any of the three
+ * payload kinds via a discriminated union, and with a generic patch()
+ * instead of one hand-rolled field list per kind.
+ *
+ * In-memory, not persisted: a daemon restart drops whatever was staged,
+ * matching emcee's own design. Bounded by both a TTL (expired items are
+ * evicted lazily on the next access) and a max item count (the oldest item
+ * is evicted to make room for a new one past that count) — never an
+ * unbounded map.
+ */
+import { randomUUID } from "node:crypto";
+import type { CreateInput, UpdateInput } from "../issue/issue.js";
+
+export const STAGE_TTL_MS = 30 * 60_000;
+export const STAGE_MAX_ITEMS = 50;
+
+export interface StageCreatePayload {
+  kind: "create";
+  backend: string;
+  input: CreateInput;
+}
+
+export interface StageUpdatePayload {
+  kind: "update";
+  ref: string;
+  input: UpdateInput;
+}
+
+export interface StageCommentPayload {
+  kind: "comment";
+  ref: string;
+  body: string;
+}
+
+export type StagePayload = StageCreatePayload | StageUpdatePayload | StageCommentPayload;
+
+export interface StagedItem {
+  id: string;
+  payload: StagePayload;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export class StagedItemNotFoundError extends Error {
+  constructor(id: string) {
+    super(`no staged item "${id}" (it may have expired -- staged items lapse after 30 minutes)`);
+    this.name = "StagedItemNotFoundError";
+  }
+}
+
+/** Only the free-text fields a patch may override, never kind/backend/ref: those are the staged item's identity, not text content to edit. */
+export type StagePatchFields = Partial<CreateInput> & Partial<UpdateInput> & { body?: string };
+
+function applyPatch(payload: StagePayload, fields: StagePatchFields): StagePayload {
+  if (payload.kind === "comment") {
+    return typeof fields.body === "string" ? { ...payload, body: fields.body } : payload;
+  }
+  const { body: _ignoredBody, ...inputFields } = fields;
+  return { ...payload, input: { ...payload.input, ...inputFields } } as StagePayload;
+}
+
+export class StageStore {
+  private readonly items = new Map<string, StagedItem>();
+
+  constructor(private readonly now: () => Date = () => new Date()) {}
+
+  add(payload: StagePayload): StagedItem {
+    this.evictExpired();
+    if (this.items.size >= STAGE_MAX_ITEMS) this.evictOldest();
+
+    const createdAt = this.now();
+    const item: StagedItem = {
+      id: randomUUID(),
+      payload,
+      createdAt: createdAt.toISOString(),
+      expiresAt: new Date(createdAt.getTime() + STAGE_TTL_MS).toISOString(),
+    };
+    this.items.set(item.id, item);
+    return item;
+  }
+
+  list(): StagedItem[] {
+    this.evictExpired();
+    return [...this.items.values()];
+  }
+
+  show(id: string): StagedItem {
+    this.evictExpired();
+    const item = this.items.get(id);
+    if (!item) throw new StagedItemNotFoundError(id);
+    return item;
+  }
+
+  patch(id: string, fields: StagePatchFields): StagedItem {
+    const item = this.show(id);
+    const patched: StagedItem = { ...item, payload: applyPatch(item.payload, fields) };
+    this.items.set(id, patched);
+    return patched;
+  }
+
+  /** Idempotent -- dropping an id that's already gone (removed, expired) is a no-op, not an error, matching this codebase's own undepend/uncontain convention. */
+  drop(id: string): boolean {
+    this.evictExpired();
+    return this.items.delete(id);
+  }
+
+  private evictExpired(): void {
+    const now = this.now().getTime();
+    for (const [id, item] of this.items) {
+      if (new Date(item.expiresAt).getTime() <= now) this.items.delete(id);
+    }
+  }
+
+  private evictOldest(): void {
+    const oldest = [...this.items.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt))[0];
+    if (oldest) this.items.delete(oldest.id);
+  }
+}