Skip to content

Add workgrid CLI, agent skill, and GitHub release pipeline - #19

Open
tathagata wants to merge 3 commits into
mainfrom
cli-release
Open

tathagata wants to merge 3 commits into
mainfrom
cli-release

Conversation

@tathagata

Copy link
Copy Markdown
Owner

Summary

  • workgrid CLI (cli/): a zero-dependency client for the /api/board application service.
    • Output: tables on a terminal, JSON envelopes when piped or with --json.
    • Usability: help for every command, suggestions for mistyped commands, doctor for setup checks, and bash/zsh/fish completion.
    • Bulk capture is atomic and idempotent, and exit codes are stable.
  • Security
    • Plaintext HTTP is allowed only to loopback hosts. Redirects and credentials embedded in the URL are refused.
    • The token is read only from the environment. Response and input sizes are capped.
    • Terminal escape sequences and bidi characters in board text are stripped in table output and escaped in JSON.
    • Destructive deletes require --yes.
  • Agent Skill for Codex, Copilot, and Claude Code.
    • It ships inside the package and at .agents/skills/workgrid/SKILL.md; a test keeps the two copies identical.
    • workgrid skill install|status|uninstall manages it.
    • Installs are atomic and all-or-nothing, refuse symbolic links, and never overwrite a skill file the CLI didn't write unless --force is passed.
  • CI: Linux, macOS, and Windows on Node 22.13 and 24. Each run checks the package contents and smoke-tests the packed tarball.
  • Release: pushing a cli-v* tag creates a GitHub Release.
    • Assets: workgrid-cli.tgz, SHA256SUMS, and a signed build-provenance attestation.
    • The tagged commit must already be on main.
    • Nothing is published to the npm registry; the package is marked "private": true.
    • Actions are pinned to commit SHAs, and Dependabot updates them after a 7-day cooldown.

Podman and private-registry container builds are deliberately left out. They're on a separate branch, local-build-private-registry-podman, until they can be tested with Podman.

Test plan

  • npm run cli:check: 48 tests pass, and the tarball allowlist check passes.
  • Read-only commands and a bulk preview run against a live local instance.
  • The packed tarball installs into a scratch prefix, and skill install --agent all works there.
  • CLI workflow passes on all six OS × Node combinations.
  • After merging, tag cli-v0.1.0 and confirm the release assets and the attestation.

🤖 Generated with Claude Code

tathagata and others added 2 commits November 8, 2026 11:55
- Zero-dependency `workgrid` CLI over the /api/board application service:
  TTY tables / JSON envelopes, per-command help, typo suggestions,
  completions (bash/zsh/fish), `doctor`, stable exit codes, bulk capture.
- Hardened transport: loopback-only plaintext HTTP, no redirects, no URL
  credentials, env-only bearer token, bounded responses, terminal-escape
  and bidi sanitization of board content.
- Agent Skill for Codex, GitHub Copilot, and Claude Code, bundled in the
  package and at .agents/skills/workgrid; `workgrid skill install` writes
  atomically, refuses symlinks, and never clobbers foreign files.
- CI on Linux/macOS/Windows x Node 22/24; tag-driven GitHub Release with
  SHA256SUMS and signed build provenance (no npm registry publish).
  Actions pinned to commit SHAs; Dependabot with a 7-day cooldown.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Windows runners checked files out with CRLF, which broke SKILL.md
frontmatter parsing and would ship CRLF in a Windows-built tarball.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tathagata

Copy link
Copy Markdown
Owner Author

@copilot review

Copilot AI commented Nov 11, 2026

Copy link
Copy Markdown

@copilot review

I found three actionable issues in the changes:

  • Medium — wrong ID reported after task creation (lib/application/board-service.ts:208): identifyChanged reports board.tasks[0], but new tasks are appended to the unfocused list, so an existing task can be reported as created.
  • Medium — deleting a nonexistent entity succeeds (lib/persistence/d1-board-repository.ts:70,78): the delete statements don't check affected rows, and execute() still increments the board revision and returns success.
  • Medium — CLI updates can overwrite concurrent edits (cli/src/commands.js:75–78,125–130): the commands read the current entity and send a full update with old values for unspecified fields, so intervening edits can be silently reverted.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Task and people updates can silently overwrite concurrent edits with stale data, while multi-target skill operations can leave partial changes after a filesystem failure.

5 open issues
What changed in this PR

Adds a zero-dependency workgrid CLI that uses the existing application API, alongside coding-agent guidance and GitHub-based distribution.

Changes:

  • Adds board-management commands, bulk capture, table/JSON output, diagnostics, and shell completion.
  • Bundles an agent skill with installation and management commands.
  • Adds cross-platform CI, package verification, and tagged releases with checksums and signed provenance.
File Description
RELEASE_NOTES.md Records CLI, skill, and release additions.
README.md Introduces CLI installation and agent integration.
package.json Adds CLI development and skill-sync scripts.
docs/​application-api.md Documents CLI transport and output contracts.
cli/​test/​modern.test.js Tests output, validation, tooling, and skill management.
cli/​test/​cli.test.js Tests API requests, errors, and bulk capture.
cli/​src/​skill.js Implements skill discovery and filesystem operations.
cli/​src/​output.js Provides sanitized text and JSON rendering.
cli/​src/​errors.js Defines structured errors and stable exit codes.
cli/​src/​commands.js Defines commands, validation, and dispatch handlers.
cli/​src/​client.js Implements bounded HTTP requests and transport safeguards.
cli/​src/​cli.js Handles arguments, help, completion, input, and diagnostics.
cli/​skills/​workgrid/​SKILL.md Bundles agent instructions for CLI usage.
cli/​scripts/​pack-check.mjs Checks package contents and dependency restrictions.
cli/​README.md Documents usage, security, installation, and releases.
cli/​package.json Defines package metadata, executable, and runtime requirements.
cli/​bin/​workgrid.js Adds the executable entry point.
cli/​.npmrc Disables lifecycle scripts for CLI package operations.
cli/​.gitignore Excludes generated tarballs.
.github/​workflows/​release-cli.yml Builds, verifies, attests, and releases tagged packages.
.github/​workflows/​cli.yml Adds cross-platform tests and packaged-CLI smoke checks.
.github/​dependabot.yml Configures grouped GitHub Actions updates.
.gitattributes Normalizes CLI, skill, and workflow line endings.
.agents/​skills/​workgrid/​SKILL.md Provides the repository-discoverable agent skill.

Review effort: Balanced

Comment thread cli/src/commands.js Outdated
if (!current) throw new CliError("NOT_FOUND", `Task ${id} not found.`, EXIT.NOT_FOUND, { field: "id" });
// Color is omitted unless requested: the service preserves the existing color.
return client.post("updateTask", compact({
id, title: options.title ?? current.title, description: options.description ?? current.description ?? "", category: options.category ?? current.category ?? "", color: options.color, colorId: options["color-id"],

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Valid. The read-modify-write could overwrite a concurrent edit, and the API offered no precondition to stop it. Fixed in d96edaa at the source:

  • updateTask and updatePerson now accept an optional expectedRevision.
  • The D1 repository applies the update and the revision bump in one revision-gated batch.
  • tasks update and people update in the CLI send the revision they read, so a concurrent change returns CONFLICT (exit 4).

The new tests/update-revision.test.ts fails without the repository change and passes with it.

Comment thread cli/src/cli.js Resolved
Comment thread cli/src/cli.js Resolved
Comment thread cli/src/commands.js Resolved
Comment thread cli/src/commands.js Resolved
…l rollback

- tasks.update / people.update accept an optional expectedRevision that the
  D1 repository enforces in the same revision-gated batch as the write. The
  CLI sends the revision it read, so a concurrent edit returns CONFLICT
  (exit 4) instead of being silently overwritten with stale fields.
- bash/zsh completion: `workgrid completion <TAB>` was shadowed by an empty
  generated case; zsh instructions now use eval after compinit, since the
  bashcompinit bridge cannot be autoloaded from $fpath.
- skill install/uninstall: restore already-written targets if a later write
  fails, and refuse a non-regular file at SKILL.md even with --force.
- bulk create: validate idempotency keys with the API's [A-Za-z0-9_-]
  allowlist before sending the preview request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tathagata
tathagata requested a balanced review from Copilot November 12, 2026 11:41

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Approval is blocked by two critical terminal-output sanitization gaps and a CLI help contract that does not match persisted category behavior.

3 open issues
1 previously missed issue

In code that hasn't changed since last review

Low severity Align empty-category help with persistence behavior

cli/​src/​commands.js:127

The help text says --category "" clears a task's category, but the application service normalizes an empty category to General before persisting it (lib/persistence/d1-board-repository.ts:73 and :97). A user or agent following this new CLI contract cannot actually clear the category; either support an empty category end-to-end or change this description to state that empty uses General.

4 resolved since last review

Review effort: Lite

Comment thread cli/src/output.js
mutation(result, style) {
const changed = result?.changed;
const revision = result?.board?.revision ?? result?.revision;
const what = changed ? `${changed.kind} ${sanitizeText(changed.id)}` : "board";
Comment thread cli/src/output.js

skill(result, style) {
const verb = { installed: "Installed", updated: "Updated", unchanged: "Already current", removed: "Removed", absent: "Not installed", "would-install": "Would install", "would-update": "Would update", "would-remove": "Would remove" };
return result.targets.map((target) => `${style.green("✓")} ${verb[target.status] ?? target.status} ${style.bold(target.agent)} skill ${style.dim(target.path)}`).join("\n");
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants