@workser/cli 0.2.4 → 0.2.5

package/AGENTS.md

@@ -42,6 +42,7 @@ what you *can* do.
 workser status | whoami                       # orient (read)
 workser project show | list                   # your pinned project + the workspace
 workser env set KEY=VALUE… | list | get KEY   # env vars
+workser env pull [--out .env.local]           # write cloud env vars into a local file
 workser db create                             # provision the Neon Postgres database
 workser db url | list                         # DB connection string + status
 workser db tables                             # list tables in the database
@@ -92,6 +93,33 @@ workser ask "<question>" [--type <t>] [--option <o>] # ask the user, WAIT for th
 #   project create, project use, env rm, domain set
 ```
 
+## Project tracking (the Board, Docs and Memory the user sees in Orbit)
+```
+workser board list | show <id>                       # what's already tracked
+workser board create "<title>" [--description <t>] [--status <s>] [--priority <p>]
+workser board move <id> <backlog|in-progress|in-review|done> | close <id>
+workser decision list | show <id>                    # what was already decided
+workser decision create "<title>" --context <t> --decision <t> [--consequences <t>]
+workser requirement list | show <id> | create "<title>" --body <t> | update <id> --status <s>
+workser doc list | show <id> [--markdown]
+workser doc create "<title>" --markdown <text> | doc update <id> --markdown <text>
+```
+**Read before you plan** — `board list` and `decision list` tell you what someone is
+already doing and what this project chose on purpose, so you don't re-file work or
+quietly reverse a decision.
+
+**A plan with phases goes on the Board before you build it.** The moment you split a
+task into more than one phase: one `board create` card per phase (only the one you're
+doing goes to `in-progress`), the plan itself as one `doc create --markdown` — with
+**no `--work-item`**, because a linked doc is shown on its card and hidden from the
+Docs panel — and a `decision create` if the plan settled a real tradeoff. A plan that
+lives only in your reply is gone as soon as the conversation scrolls.
+
+**Keep it true as you work.** `board move <id> in-progress` when you pick it up,
+`in-review` when it's ready to look at, `board close <id>` when it's done and
+verified. A Board still reading `backlog` after you shipped is worse than no Board.
+Decisions are append-only: supersede an old one with a new record, never edit it.
+
 ## Memory (remember across conversations, not just this one)
 Every conversation you run is otherwise a fresh start — no memory of what you or the
 user decided last time. `workser memory add "<content>"` fixes that: it stores durable,
@@ -205,8 +233,12 @@ keep your own context lean and get a specialized second perspective; a non-zero
 ## Example
 ```bash
 workser status --json                  # orient: which project, last deploy
+workser board list --json              # what's tracked; decision list for what's decided
+workser board create "Phase 1 — …" --status in-progress --json   # phased plan -> cards
+workser doc create "Plan" --markdown "…" --json                  # …plus the plan doc
 workser env set STRIPE_KEY=sk_live_… --json
 # … you write the app code with your normal tools …
 workser deploy --prod --watch --json   # -> .data.url is the live URL
+workser board close <id> --json        # the Board now matches reality
 ```
 Report results to the user in plain language, not raw JSON.

package/dist/index.js

@@ -4243,6 +4243,33 @@ purpose \u2014 \`workser decision show <id>\` gives you the context and conseque
 not just the title. Reach for \`workser doc list\` / \`workser requirement list\`
 the same way when the task touches documented behaviour.
 
+## Work with phases \u2192 cards + a plan doc, before you build
+
+The moment you split a task into more than one phase, file it \u2014 not afterwards,
+and not only in your reply, which is gone once the conversation scrolls.
+
+\`\`\`bash
+# one card per phase; only the one you're doing goes to in-progress
+workser board create "Phase 1 \u2014 schema + migration" \\
+  --description "Add orders/line_items tables and the migration." \\
+  --status in-progress --json
+workser board create "Phase 2 \u2014 checkout API" --description "\u2026" --json
+workser board create "Phase 3 \u2014 cart UI"      --description "\u2026" --json
+
+# the plan itself, ONE doc, deliberately NOT linked to a card
+workser doc create "Checkout \u2014 implementation plan" --markdown "$(cat plan.md)" --json
+
+# the approach, if the plan settled something with real alternatives
+workser decision create "Carts live server-side" --context "\u2026" --decision "\u2026" --json
+\`\`\`
+
+**Don't pass \`--work-item\` for a multi-phase plan.** A linked document renders on
+its card and is *hidden* from the Docs panel; a plan spanning three phases belongs
+to the project, not to phase 1.
+
+The bar: if the user closed this conversation now, the Board should still show
+what's left and the doc should still explain the plan to whoever continues it.
+
 ## Keep the Board honest while you work
 
 A Board still reading \`backlog\` after the feature shipped tells the user the
@@ -4307,8 +4334,8 @@ workser doc update <id> --markdown "$(cat updated.md)"
 
 Record what a future maintainer would need: follow-up work you found but didn't
 do, a choice between real alternatives, a behaviour worth writing down. Don't
-narrate every small step \u2014 and never treat filing a card as a substitute for
-the work. Creating a Board card that says "fix the bug" is not fixing the bug.
+narrate every small step \u2014 and never treat filing a card as a substitute for the
+work. A card saying "fix the bug" is not fixing the bug.
 `
   },
   {
@@ -5373,6 +5400,7 @@ async function presign(ctx, projectId, bucket, key, operation, expiresInSeconds)
 
 // src/commands/env.ts
 var import_picocolors9 = __toESM(require_picocolors(), 1);
+import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
 function appQuery(opts) {
   const app = typeof opts?.app === "string" ? opts.app : "";
   return app ? `?webAppId=${encodeURIComponent(app)}` : "";
@@ -5429,6 +5457,59 @@ function registerEnv(program3) {
       })
     )
   );
+  env.command("pull").description("Write this app's cloud env vars into a local file (default .env.local)").option("--app <webAppId>", APP_FLAG_HELP).option("--out <file>", "Local file to write", ".env.local").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      const items = await api(
+        ctx,
+        `/v1/projects/${projectId}/env${appQuery(opts)}`
+      );
+      const outPath = typeof opts?.out === "string" ? opts.out : ".env.local";
+      if (!items?.length) {
+        return ok(
+          { file: outPath, pulled: [] },
+          () => line(import_picocolors9.default.dim("No cloud variables to pull."))
+        );
+      }
+      const pulled = [];
+      for (const item of items) {
+        const res = await api(
+          ctx,
+          `/v1/projects/${projectId}/env/${encodeURIComponent(item.key)}${appQuery(opts)}`
+        );
+        pulled.push({ key: item.key, value: res?.value ?? "" });
+      }
+      await mergeEnvFile(outPath, pulled);
+      ok(
+        { file: outPath, pulled: pulled.map((p) => p.key) },
+        () => success(
+          `Pulled ${pulled.length} variable(s) into ${import_picocolors9.default.bold(outPath)}.`
+        )
+      );
+    })
+  );
+}
+var ENV_KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=/;
+async function mergeEnvFile(path, vars) {
+  const existing = await readFile3(path, "utf8").catch(() => "");
+  const lines = existing.length ? existing.split(/\r?\n/) : [];
+  const remaining = new Map(vars.map((v) => [v.key, v.value]));
+  const merged = lines.map((rawLine) => {
+    const match = ENV_KEY_LINE.exec(rawLine);
+    if (!match || !remaining.has(match[1])) return rawLine;
+    const key = match[1];
+    const value = remaining.get(key);
+    remaining.delete(key);
+    return `${key}=${formatEnvValue(value)}`;
+  });
+  while (merged.length && merged[merged.length - 1] === "") merged.pop();
+  for (const [key, value] of remaining) {
+    merged.push(`${key}=${formatEnvValue(value)}`);
+  }
+  await writeFile3(path, merged.join("\n") + "\n", "utf8");
+}
+function formatEnvValue(value) {
+  return /[\s"'#]/.test(value) ? JSON.stringify(value) : value;
 }
 
 // src/commands/deploy.ts
@@ -6221,7 +6302,7 @@ function printRun(run) {
 }
 
 // src/commands/image.ts
-import { writeFile as writeFile3, mkdir } from "fs/promises";
+import { writeFile as writeFile4, mkdir } from "fs/promises";
 import { dirname as dirname2, resolve as resolve3 } from "path";
 function registerImage(program3) {
   const image = program3.command("image").description("Generate images from a text prompt");
@@ -6286,7 +6367,7 @@ async function download(url, output) {
     );
   }
   await mkdir(dirname2(target), { recursive: true });
-  await writeFile3(target, Buffer.from(await res.arrayBuffer()));
+  await writeFile4(target, Buffer.from(await res.arrayBuffer()));
   return target;
 }
 
@@ -6972,7 +7053,7 @@ function unwrap(group) {
 
 // src/index.ts
 var pkg = {
-  version: true ? "0.2.4" : "0.0.0-dev"
+  version: true ? "0.2.5" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",

package/skills/workser/SKILL.md

@@ -35,10 +35,9 @@ command. Don't print them all; you are paying for every line you load.
 | Record finished output, or ask the user a question | `artifact …`, `ask` | `workser help deliverables` |
 | Control this machine — files, shell, screen, browser | `tool …` | `workser help computer-use` |
 
-`workser help` with no topic lists them. **The CLI is the source of truth**: it ships
-these guides with itself, so they match the version you are running. For exact flags
-on any command, `workser <command> --help` is generated from the implementation and
-cannot be out of date.
+`workser help` with no topic lists them. **The CLI is the source of truth** — it
+ships these guides itself, so they match the version you are running, and
+`workser <command> --help` is generated from the implementation.
 
 ## Orientation (no guide needed)
 
@@ -61,13 +60,11 @@ SQL, provision the bucket + auth, deploy, set env vars, manage files. Sensitive
 actions are **gated** — the daemon may return `error.code = "awaiting_approval"`
 (exit 5) and wait for the user to approve in Orbit; ask them to approve, then retry.
 
-What you **cannot** do is administer the project set or destroy config: creating or
-switching which project is pinned, deleting env vars, or attaching a custom domain.
-Those return `error.code = "owner_only"` (exit 6) — tell the user it's an owner
-action to do in Orbit, then continue with what you can do. The project is already
-selected; you don't pick or switch it.
-
-Owner-only, for reference: `project create` · `project use` · `env rm` · `domain set`.
+What you **cannot** do is administer the project set or destroy config:
+`project create` · `project use` · `env rm` · `domain set` return
+`error.code = "owner_only"` (exit 6). Tell the user it's an owner action to do in
+Orbit, then continue with what you can. The project is already selected; you don't
+pick or switch it.
 
 ## Golden rules
 
@@ -80,19 +77,24 @@ Owner-only, for reference: `project create` · `project use` · `env rm` · `dom
    (what was already decided, so you don't quietly reverse it), and
    `workser design show --json` before writing UI. This project outlives your
    session; that context is how you don't start from zero.
-3. **Stay in your lane.** `error.code = "owner_only"` (exit 6) means the action is
+3. **A phased plan goes on the Board before you build it.** One `board create`
+   card per phase, the plan itself as one `doc create` (no `--work-item`, or it's
+   hidden from the Docs panel), and a `decision create` if it settled a real
+   tradeoff. A plan that lives only in your reply is gone when the conversation
+   scrolls. Details: `workser help sdlc-entities`.
+4. **Stay in your lane.** `error.code = "owner_only"` (exit 6) means the action is
    reserved for the owner in Orbit. Don't retry or look for a workaround — tell the
    user, then continue. Provisioning the *pinned project's own* db / bucket / auth is
    allowed (it may be approval-gated, not owner-only).
-4. **Approvals are normal.** Some allowed actions may return
+5. **Approvals are normal.** Some allowed actions may return
    `{"error":{"code":"awaiting_approval"}}` (exit 5) while the user approves in the
    Orbit UI. Tell the user to approve, then retry — do **not** try to bypass it.
-5. **Never ask for or store credentials.** Auth is handled by Orbit; you never see keys.
-6. **Verify before "done".** Before telling the user a task is complete, run
+6. **Never ask for or store credentials.** Auth is handled by Orbit; you never see keys.
+7. **Verify before "done".** Before telling the user a task is complete, run
    `workser verify --json` (runs the project's typecheck/lint/build). If it
    reports `"ok": false`, fix the errors it lists and re-run until it passes —
    a green build is the bar for "done", not your own judgement.
-7. **Destructive shell actions are blocked.** Irreversible commands (`rm -rf /`,
+8. **Destructive shell actions are blocked.** Irreversible commands (`rm -rf /`,
    `git reset --hard`, `DROP`/`TRUNCATE`, `curl | sh`, …) are refused by Workser's
    safety policy — don't attempt them; use migrations + scoped changes instead.
 
@@ -102,19 +104,16 @@ Owner-only, for reference: `project create` · `project use` · `env rm` · `dom
 workser status --json                       # 1. orient (project is already pinned)
 workser board list --json                   # 2. what's already tracked
 workser decision list --json                #    …and already decided
-workser board move <id> in-progress --json  # 3. claim the card you're doing
-workser db create --json                    # 4. provision infra the app needs (idempotent)
-workser env set STRIPE_KEY=sk_live_… --json # 5. configure it
+workser board create "Phase 2 — …" --json   # 3. phases? file them + the plan doc
+workser board move <id> in-progress --json  # 4. claim the card you're doing
+workser db create --json                    # 5. provision infra the app needs (idempotent)
+workser env set STRIPE_KEY=sk_live_… --json # 6. configure it
 # … you write the app code with your normal tools …
-workser verify --json                       # 6. green build is the bar for "done"
-workser deploy --prod --watch --json        # 7. ship; returns the live URL
-workser board close <id> --json             # 8. the Board now matches reality
+workser verify --json                       # 7. green build is the bar for "done"
+workser deploy --prod --watch --json        # 8. ship; returns the live URL
+workser board close <id> --json             # 9. the Board now matches reality
 ```
 
-Provisioning the pinned project's own database / bucket / auth is yours to do
-(`db create`, `storage create`, `auth enable`) — the user may need to approve it in
-Orbit (`awaiting_approval`). Only a **custom domain** is an owner action.
-
 ## Reading results
 
 - Success: use `.data` (e.g. `.data.url` after deploy, `.data` array after `list`).

package/skills/workser/reference/sdlc-entities.md

@@ -55,6 +55,33 @@ purpose — `workser decision show <id>` gives you the context and consequences,
 not just the title. Reach for `workser doc list` / `workser requirement list`
 the same way when the task touches documented behaviour.
 
+## Work with phases → cards + a plan doc, before you build
+
+The moment you split a task into more than one phase, file it — not afterwards,
+and not only in your reply, which is gone once the conversation scrolls.
+
+```bash
+# one card per phase; only the one you're doing goes to in-progress
+workser board create "Phase 1 — schema + migration" \
+  --description "Add orders/line_items tables and the migration." \
+  --status in-progress --json
+workser board create "Phase 2 — checkout API" --description "…" --json
+workser board create "Phase 3 — cart UI"      --description "…" --json
+
+# the plan itself, ONE doc, deliberately NOT linked to a card
+workser doc create "Checkout — implementation plan" --markdown "$(cat plan.md)" --json
+
+# the approach, if the plan settled something with real alternatives
+workser decision create "Carts live server-side" --context "…" --decision "…" --json
+```
+
+**Don't pass `--work-item` for a multi-phase plan.** A linked document renders on
+its card and is *hidden* from the Docs panel; a plan spanning three phases belongs
+to the project, not to phase 1.
+
+The bar: if the user closed this conversation now, the Board should still show
+what's left and the doc should still explain the plan to whoever continues it.
+
 ## Keep the Board honest while you work
 
 A Board still reading `backlog` after the feature shipped tells the user the
@@ -119,5 +146,5 @@ workser doc update <id> --markdown "$(cat updated.md)"
 
 Record what a future maintainer would need: follow-up work you found but didn't
 do, a choice between real alternatives, a behaviour worth writing down. Don't
-narrate every small step — and never treat filing a card as a substitute for
-the work. Creating a Board card that says "fix the bug" is not fixing the bug.
+narrate every small step — and never treat filing a card as a substitute for the
+work. A card saying "fix the bug" is not fixing the bug.