argsbarg 5.1.5 → 5.1.7

package/CHANGELOG.md

@@ -7,18 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.7] - 2026-07-05
+
+### Changed
+
+- **Homebrew install docs** — private taps: `brew install gh` and `gh auth login` only; removed legacy token env-var setup from docs and justfiles (template + consumers).
+- **App config array input** — interactive `configure` and `configure set` parse homogeneous primitive arrays from comma-separated values or JSON literals; objects and nested arrays still require `--json`.
+- **Homebrew formula `uninstall`** — generated formulae run `{key} configure --remove-config --yes` before the keg is removed (template + docs).
+
+## [5.1.6] - 2026-07-05
+
+
 ## [5.1.5] - 2026-07-05
 
 ### Changed
 
-- **`just install-local`** — back up release `Formula/{key}.rb`, write dev formula for `brew install`, then restore the release formula (`scripts/with-dev-formula.ts`).
-- **`just ensure-release-formula`** — normalize release formula layout; restore from install-local backup or fail with `git restore` hint if a dev `file://` formula is left on disk.
+- **`just install-local`** — back up release `Formula/{key}.rb`, write dev formula for `brew install`, then restore (`scripts/with-dev-formula.ts`; dropped `gen-dev-formula.ts` / `dev-formula.ts`).
 
 ## [5.1.4] - 2026-07-04
 
 ### Changed
 
-- **Template justfile** — export `HOMEBREW_GITHUB_API_TOKEN` from `gh auth token` at top of justfile; removed `scripts/ensure-brew-github-token.sh` and `HOMEBREW_NO_*` suppress vars.
+- **Template justfile** — removed `scripts/ensure-brew-github-token.sh` and `HOMEBREW_NO_*` suppress vars.
 
 ## [5.1.3] - 2026-07-04
 
@@ -26,7 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **Private GitHub release installs** — release formulae use `GitHubPrivateReleaseDownloadStrategy` (GitHub API + `GitHub::API.credentials` / `HOMEBREW_GITHUB_API_TOKEN`); `just install-production` and `just test-release` export the token (with `gh auth token` fallback). Documented in `docs/distribution-homebrew.md`.
+- **Private GitHub release installs** — release formulae use `GitHubPrivateReleaseDownloadStrategy` (GitHub API + `GitHub::API.credentials`); documented in `docs/distribution-homebrew.md`.
 - **Homebrew install docs** — README template and consumer READMEs document private-tap install; `configure` CLI notes stay post-install only.
 
 ## [5.1.1] - 2026-07-04
@@ -617,7 +627,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.5...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.7...HEAD
+[5.1.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.7
+[5.1.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.6
 [5.1.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.5
 [5.1.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.4
 [5.1.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.3

package/README.md

@@ -112,11 +112,13 @@ See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom
 
 ### Configure CLI
 
-Ship via **Homebrew** (tap-from-repo). The formula installs the binary and shell completions; `post_install` runs agent artifact refresh. Private taps need `HOMEBREW_GITHUB_API_TOKEN` on install — see [docs/distribution-homebrew.md](docs/distribution-homebrew.md#end-user-install).
+Ship via **Homebrew** (tap-from-repo). The formula installs the binary and shell completions; `post_install` runs agent artifact refresh. Private taps require `gh auth login` — see [docs/distribution-homebrew.md](docs/distribution-homebrew.md#end-user-install).
 
 ```bash
+brew install gh
+gh auth login
 brew tap <org>/<repo> git@github.com:<org>/<repo>.git
-HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install <tap>/myapp
+brew install <tap>/myapp
 myapp configure    # interactive per-target setup; opt-in app config wizard
 ```
 
@@ -264,7 +266,7 @@ To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-progr
 | Command layout | `src/commands/<name>/command.ts`; registration in `src/program.ts` |
 | MCP doc topics | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |
 | Package import | `from "argsbarg"` (not relative to argsbarg `src/`) |
-| Homebrew distribution | `scripts/formula-shared.ts`, `scripts/gen-dev-formula.ts`, `Formula/`, `justfile` |
+| Homebrew distribution | `scripts/formula-shared.ts`, `scripts/with-dev-formula.ts`, `Formula/`, `justfile` |
 | Dev tooling | Biome (`just format` / `just lint`), TypeScript, colocated tests |
 | Cursor rules | `.cursor/rules/cli-program.mdc`, `.cursor/rules/code.mdc` |
 

package/docs/config-schema.md

@@ -202,7 +202,7 @@ When `program.appConfig` is set and `commands !== false`:
 
 `configure get`/`set` skip required-config exit and TTY prompts. Sensitive values redact on `get` (`REDACTED` / `{ "set": true }` with `--json`).
 
-Object/array/`$ref` properties require `--json` on `configure set`.
+Object/array/`$ref` properties require `--json` on `configure set` when comma-separated or JSON-literal input does not apply (e.g. objects, arrays of objects). Homogeneous primitive arrays (`string[]`, `number[]`, `integer[]`, `boolean[]`, and `string[]` with `format: date` / `date-time` on items) accept comma-separated values or a JSON array in both `configure set` and interactive `configure`.
 
 ## Example in this repo
 

package/docs/configure.md

@@ -6,15 +6,15 @@ Opt out with `configure: { enabled: false }` on the program root.
 
 ## End-user install (Homebrew)
 
-Private GitHub release downloads require `HOMEBREW_GITHUB_API_TOKEN` on `brew install` and `brew upgrade`. See [distribution-homebrew.md](distribution-homebrew.md#end-user-install) for token setup (`gh auth token` or a personal access token with **Contents** read).
+Private GitHub release downloads require [GitHub CLI](https://cli.github.com/) authentication for `brew install` and `brew upgrade`. See [distribution-homebrew.md](distribution-homebrew.md#end-user-install) (`brew install gh`, then `gh auth login`).
 
 ```bash
 brew tap <org>/<repo> git@github.com:<org>/<repo>.git
-HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install <tap>/<key>
+brew install <tap>/<key>
 <key> configure    # interactive: per-target prompts; run when app config is required
 ```
 
-Upgrade with `HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew upgrade <key>`. Shell completions are installed by Homebrew during `brew install`. Users must configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
+Upgrade with `brew upgrade <key>`. Shell completions are installed by Homebrew during `brew install`. Users must configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
 **Uninstall the binary:** remove agent artifacts first (while the CLI is still on PATH), then `brew uninstall`:
 
@@ -23,11 +23,13 @@ Upgrade with `HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew upgrade <key>`.
 brew uninstall <tap>/<key>
 ```
 
+`brew uninstall` runs the formula `uninstall` hook, which removes app config (`configure --remove-config --yes`). Skills and MCP entries are not removed by Homebrew — use `--remove-all` before uninstall when you want those gone too.
+
 ## Developer install
 
 ```bash
 just build
-just install-local    # same formula as production; gen-dev-formula uses file:// URL (`just install` is an alias)
+just install-local    # same formula as production; temporary file:// URL during brew install (`just install` is an alias)
 ```
 
 Dev flow matches release: formula `install` copies the binary and generates completions; `post_install` runs `<key> configure --sync --yes` for skills/MCP. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles (skips completions and `post_install`). Use `just sync-artifacts` to refresh agent artifacts without touching the binary.
@@ -67,7 +69,7 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 | Claude skill | Y/n prompt | `~/.claude/skills/<dir>/` when `~/.claude` exists |
 | Codex / OpenCode / OpenClaw skills | Y/n prompt | Agent-specific dirs when available |
 | MCP config | Y/n prompt when `mcpServer.enabled` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
-| App config | auto-runs wizard | Interactive wizard writes `~/.local/lib/<key>/config.json` |
+| App config | auto-runs wizard | Interactive wizard writes `~/.local/lib/<key>/config.json` (schema-aware: comma-separated or JSON for primitive arrays) |
 
 ### Externally managed binary (Homebrew)
 
@@ -163,6 +165,18 @@ end
 
 This refreshes skills/MCP without running the configure wizard (app config is opt-in via interactive `configure`).
 
+## Formula `uninstall`
+
+Release formulae should run:
+
+```ruby
+def uninstall
+  system bin/"myapp", "configure", "--remove-config", "--yes"
+end
+```
+
+Homebrew calls this before removing the keg, so the binary is still on PATH. Safe no-op when app config was never created or `program.appConfig` is unset.
+
 ## Bootstrapping a new CLI
 
 ```bash

package/docs/distribution-homebrew.md

@@ -9,38 +9,34 @@ Argsbarg apps distribute the **binary and shell completions** through Homebrew,
 | Binary + completions | Formula `install` block |
 | Skills + MCP | Formula `post_install` → `{key} configure --sync --yes` |
 | App config | User opt-in: `{key} configure` (interactive; not run from formula `post_install`) |
+| App config cleanup | Formula `uninstall` → `{key} configure --remove-config --yes` |
 
 **Only tap-from-repo** — in-repo `Formula/` or GitHub tap. Not Homebrew core.
 
 ### End-user install
 
-For **private or internal GitHub taps**, prepend `HOMEBREW_GITHUB_API_TOKEN` on `brew install` and `brew upgrade` (release formulae download via the GitHub API).
-
-If [GitHub CLI](https://cli.github.com/) is installed:
+For **private or internal GitHub taps**, authenticate with GitHub CLI before `brew install` or `brew upgrade` (release formulae download via the GitHub API; Homebrew discovers credentials from `gh auth login`).
 
 ```bash
-brew tap <org>/<repo> git@github.com:<org>/<repo>.git
-HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install <tap>/{key}
-{key} configure   # when app config is required
+brew install gh   # skip if already installed
+gh auth login     # skip if already authenticated
 ```
 
-Without `gh`, create a personal access token at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new):
-
-- Resource owner — your org (e.g. sqsp)
-- Repository access — the tap repo or all repositories
-- Permissions — **Contents** (read-only)
+Then:
 
 ```bash
-HOMEBREW_GITHUB_API_TOKEN=YOUR_TOKEN brew install <tap>/{key}
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+brew install <tap>/{key}
+{key} configure   # when app config is required
 ```
 
 Upgrade:
 
 ```bash
-HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew upgrade {key}
+brew upgrade {key}
 ```
 
-Local dev installs (`just install-local`) use a `file://` staging URL and do not need the token.
+Local dev installs (`just install-local`) use a `file://` staging URL and do not need GitHub authentication.
 
 ### Developer install
 
@@ -48,7 +44,7 @@ Local dev installs (`just install-local`) use a `file://` staging URL and do not
 just build
 just install-local    # or `just install` (alias)
 just reinstall-local   # fast binary swap (`install -m 755` into Cellar; run install-local first)
-just uninstall        # undo formula + agent artifacts (not app config)
+just uninstall        # undo formula + agent artifacts (app config removed by formula uninstall)
 ```
 
 Dev and release use the **same formula file** (`Formula/{key}.rb`, class name, install/post_install/test). `just install-local` temporarily overwrites it with a `file://` dev formula (staged under `Formula/.staging/`), runs `brew install`, then **restores** the release formula from backup. Release bumps rewrite the GitHub URL via `scripts/release.ts`.
@@ -57,13 +53,13 @@ Dev and release use the **same formula file** (`Formula/{key}.rb`, class name, i
 
 | Recipe | Removes |
 | --- | --- |
-| `just uninstall` | Formula `{key}` + tap symlink + skills/MCP |
+| `just uninstall` | Formula `{key}` + tap symlink + skills/MCP; app config via formula `uninstall` |
 | `just uninstall-config` | App config file only (`configure --remove-config --yes`) |
-| `just uninstall-release` | Release formula from `{tap}` (keeps tap) |
-| `just uninstall-release-tap` | Release formula + `brew untap {tap}` |
+| `just uninstall-release` | Release formula from `{tap}` (keeps tap; app config via formula `uninstall`) |
+| `just uninstall-release-tap` | Release formula + `brew untap {tap}` (app config via formula `uninstall`) |
 | `just test-release` | Install release formula and run formula test |
 
-End users: `<key> configure --remove-all --yes` then `brew uninstall <tap>/<key>`.
+End users: `<key> configure --remove-all --yes` then `brew uninstall <tap>/<key>`. `brew uninstall` also removes app config via the formula `uninstall` hook (skills/MCP are not removed automatically).
 
 ## Formula pattern
 
@@ -76,9 +72,13 @@ end
 def post_install
   system bin/"{key}", "configure", "--sync", "--yes"
 end
+
+def uninstall
+  system bin/"{key}", "configure", "--remove-config", "--yes"
+end
 ```
 
-Release formulae generated by `scripts/formula-shared.ts` embed a `GitHubPrivateReleaseDownloadStrategy` that resolves the release asset through the GitHub API at download time and authenticates with `GitHub::API.credentials` (backed by `HOMEBREW_GITHUB_API_TOKEN`, `gh auth`, or other Homebrew GitHub credential sources):
+Release formulae generated by `scripts/formula-shared.ts` embed a `GitHubPrivateReleaseDownloadStrategy` that resolves the release asset through the GitHub API at download time and authenticates with `GitHub::API.credentials` (Homebrew discovers `gh auth login` automatically):
 
 ```ruby
 url "https://github.com/<org>/<repo>/releases/download/vX.Y.Z/{key}",

package/examples/full-example/README.md

@@ -22,30 +22,25 @@ Requires [Homebrew](https://brew.sh).
 
 ### End users
 
-Private GitHub release downloads require `HOMEBREW_GITHUB_API_TOKEN` on `brew install` and `brew upgrade`.
-
-If [GitHub CLI](https://cli.github.com/) is installed:
+Private GitHub release downloads require [GitHub CLI](https://cli.github.com/) authentication. Run once before `brew install` or `brew upgrade`:
 
 ```bash
-brew tap bdombro/bun-argsbarg git@github.com:bdombro/bun-argsbarg.git
-HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install bdombro/bun-argsbarg/full-example
-full-example configure
+brew install gh   # skip if already installed
+gh auth login     # skip if already authenticated
 ```
 
-Without `gh`, create a personal access token at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new):
-
-- Resource owner — your org
-- Repository access — this repo (or all repositories)
-- Permissions — **Contents** (read-only)
+Install:
 
 ```bash
-HOMEBREW_GITHUB_API_TOKEN=YOUR_TOKEN brew install bdombro/bun-argsbarg/full-example
+brew tap bdombro/bun-argsbarg git@github.com:bdombro/bun-argsbarg.git
+brew install bdombro/bun-argsbarg/full-example
+full-example configure
 ```
 
 Upgrade:
 
 ```bash
-HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew upgrade full-example
+brew upgrade full-example
 ```
 
 Shell completions install during `brew install`. See [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
@@ -59,11 +54,11 @@ brew install just bun
 just setup
 just install              # build + local dev formula
 just reinstall-local      # fast binary swap during development
-just install-production   # remote tap install (uses gh auth token)
+just install-production   # remote tap install (requires gh auth login)
 just test-release
 ```
 
-Undo a local dev install: `just uninstall` (formula + agent artifacts), `just uninstall-config` (app config only).
+Undo a local dev install: `just uninstall` (formula + agent artifacts; app config removed by formula `uninstall`), `just uninstall-config` (app config only, without uninstalling the formula).
 
 ## Schemagen markers
 

package/examples/full-example/justfile

@@ -1,7 +1,5 @@
 set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
 
-export HOMEBREW_GITHUB_API_TOKEN := `gh auth token`
-
 cli_key := `bun scripts/print-identity.ts key`
 tap_org := `bun scripts/print-identity.ts tapOrg`
 tap_repo := `bun scripts/print-identity.ts tapRepo`
@@ -49,12 +47,8 @@ install: install-local
 sync-artifacts:
     just run configure --sync --yes
 
-# Normalize release formula (fix leftover dev formula or stale layout)
-ensure-release-formula:
-    bun scripts/ensure-release-formula.ts
-
 # Dev install: build, dev formula (restored after brew), symlink tap, brew install
-install-local: build ensure-release-formula
+install-local: build
     @brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
@@ -62,7 +56,7 @@ install-local: build ensure-release-formula
     @echo ""
     @echo "Next: {{cli_key}} configure"
 
-# Remove local dev install, then install from GitHub tap (private release assets need gh auth token)
+# Remove local dev install, then install from GitHub tap (requires gh auth login)
 install-production: uninstall
     brew tap {{release_repo}} {{tap_git_url}}
     brew install --formula {{release_repo}}/{{cli_key}}

package/examples/full-example/scripts/formula-shared.ts

@@ -14,6 +14,10 @@ export const formulaPostInstallRuby = `def post_install
     system bin/"${key}", "configure", "--sync", "--yes"
   end`;
 
+export const formulaUninstallRuby = `def uninstall
+    system bin/"${key}", "configure", "--remove-config", "--yes"
+  end`;
+
 export const formulaCaveatsRuby = `def caveats
     <<~EOS
       Run \`${key} configure\` to set up agent artifacts and app config (interactive).
@@ -93,6 +97,8 @@ export function renderFormula(coords: FormulaCoords): string {
 
   ${formulaPostInstallRuby}
 
+  ${formulaUninstallRuby}
+
   ${formulaCaveatsRuby}
 
   ${formulaTestRuby}

package/examples/full-example/scripts/with-dev-formula.ts

@@ -1,8 +1,47 @@
 #!/usr/bin/env bun
+
 /** Back up release formula, write dev formula, run a command, then restore. Usage: bun scripts/with-dev-formula.ts -- brew install … */
 
 import { spawnSync } from "node:child_process";
-import { backupReleaseFormula, releaseFormulaPath, restoreReleaseFormula, writeDevFormula } from "./dev-formula.ts";
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createIdentity } from "./create-identity.ts";
+import { renderDevFormula } from "./formula-shared.ts";
+
+const { key } = createIdentity;
+const root = join(import.meta.dir, "..");
+const stagingDir = join(root, "Formula", ".staging");
+const stagingPath = join(stagingDir, key);
+const formulaPath = join(root, "Formula", `${key}.rb`);
+const backupPath = join(stagingDir, `${key}.rb.bak`);
+
+function backupReleaseFormula(): void {
+  if (!existsSync(formulaPath)) {
+    return;
+  }
+  mkdirSync(stagingDir, { recursive: true });
+  copyFileSync(formulaPath, backupPath);
+}
+
+function restoreReleaseFormula(): void {
+  if (!existsSync(backupPath)) {
+    return;
+  }
+  copyFileSync(backupPath, formulaPath);
+  unlinkSync(backupPath);
+}
+
+function writeDevFormula(): void {
+  const distPath = join(root, "dist", key);
+  mkdirSync(stagingDir, { recursive: true });
+  copyFileSync(distPath, stagingPath);
+  chmodSync(stagingPath, 0o755);
+
+  const sha256 = createHash("sha256").update(readFileSync(stagingPath)).digest("hex");
+  const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version as string;
+  writeFileSync(formulaPath, renderDevFormula(stagingPath, version, sha256), "utf8");
+}
 
 const sep = process.argv.indexOf("--");
 if (sep === -1 || sep === process.argv.length - 1) {
@@ -31,5 +70,5 @@ try {
 }
 
 if (process.exitCode === 0) {
-  console.log(`Restored ${releaseFormulaPath()}`);
+  console.log(`Restored ${formulaPath}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "5.1.5",
+  "version": "5.1.7",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/builtins/builtins.test.ts

@@ -42,7 +42,6 @@ describe("builtins help copy", () => {
     expect(configure.description).toContain("agent skills");
     expect(configure.description).toContain("MCP config");
     expect(configure.notes).toContain("brew upgrade");
-    expect(configure.notes).not.toContain("HOMEBREW_GITHUB_API_TOKEN");
     const names = configureBuiltinOptions(fixture).map((o) => o.name);
     expect(names).toContain("sync");
     expect(names).toContain("remove-all");

package/src/builtins/config.ts

@@ -178,7 +178,8 @@ function configSetLeaf(program: CliProgram, mcpSetEnabled: boolean): CliLeaf {
       },
       {
         name: "value",
-        description: "Value to store (use --json for objects/arrays).",
+        description:
+          "Value to store (comma-separated or JSON for primitive arrays; --json for objects and nested arrays).",
         kind: CliOptionKind.String,
         argMin: 0,
         argMax: 1,

package/src/builtins/configure-copy.ts

@@ -72,6 +72,8 @@ export function configureCommandNotes(program: CliProgram, _caps: CliCapabilitie
     `  ${app} configure --remove-all --yes`,
     `  brew uninstall <tap>/${app}`,
     "",
+    "App config is removed automatically by the formula uninstall hook during brew uninstall.",
+    "",
   ];
   if (program.appConfig) {
     lines.push("Remove app config only:", `  ${app} configure --remove-config --yes`, "");

package/src/config/bootstrap.ts

@@ -29,7 +29,8 @@ import {
   resolveAppConfig,
   stringifyConfigValue,
 } from "./resolve.ts";
-import { effectiveJsonSchema } from "./schema.ts";
+import { configPropertySchema, effectiveJsonSchema } from "./schema.ts";
+import { configValueInputHint, parseConfigSetValue } from "./validate.ts";
 
 export { displayAppConfigPath } from "./file.ts";
 
@@ -148,11 +149,15 @@ function promptConfigKey(
   configure: boolean,
   jsonSchemaRequired: Set<string> | undefined,
   hostEnv: Record<string, string | undefined>,
+  jsonSchema: Record<string, unknown> | undefined,
 ): { value: unknown; userTyped: boolean } {
   const baseTitle = entry.title ?? defaultConfigEntryTitle(key);
   const titleWithEnv = entry.env ? `${baseTitle} (${entry.env})` : baseTitle;
   const required = configEntryRequired(key, entry, jsonSchemaRequired);
   const heading = required || !configure ? titleWithEnv : `${titleWithEnv} (optional)`;
+  const propSchema = jsonSchema ? configPropertySchema(jsonSchema, key) : undefined;
+  const valueHint = jsonSchema ? configValueInputHint(propSchema, jsonSchema) : undefined;
+  const valueHintSuffix = valueHint ? ` (${valueHint})` : "";
   process.stderr.write(`${heading}\n`);
   process.stderr.write(`  ${entry.description}\n`);
   const hasCurrent = current !== undefined && current !== null && String(current).length > 0;
@@ -160,18 +165,20 @@ function promptConfigKey(
   if (hasCurrent) {
     process.stderr.write(`  Current: ${sensitive ? "REDACTED" : stringifyConfigValue(current)}\n`);
     const acceptPrompt = resolvedFromEnv(entry, hostEnv)
-      ? `  Value (Enter to copy from env): `
-      : `  Value (Enter to keep): `;
+      ? `  Value (Enter to copy from env)${valueHintSuffix}: `
+      : `  Value (Enter to keep)${valueHintSuffix}: `;
     process.stderr.write(acceptPrompt);
   } else {
-    process.stderr.write(`  Value: `);
+    process.stderr.write(`  Value${valueHintSuffix}: `);
   }
   const input = readPromptLine(sensitive);
   if (input.length === 0 && hasCurrent) {
     return { value: current, userTyped: false };
   }
   if (input.length > 0) {
-    return { value: input, userTyped: true };
+    const rootSchema = jsonSchema ?? { type: "object", properties: {} };
+    const parsed = parseConfigSetValue(input, propSchema, rootSchema, false);
+    return { value: parsed, userTyped: true };
   }
   return { value: undefined, userTyped: false };
 }
@@ -219,7 +226,15 @@ function promptMissingRequired(program: CliProgram): Record<string, unknown> {
       writeConfigureSetupHeading();
       headingWritten = true;
     }
-    const { value, userTyped } = promptConfigKey(key, entry, undefined, false, fromSchema, hostEnv);
+    const { value, userTyped } = promptConfigKey(
+      key,
+      entry,
+      undefined,
+      false,
+      fromSchema,
+      hostEnv,
+      jsonSchema,
+    );
     if (value !== undefined && String(value).length > 0) {
       updates[key] = value;
     }
@@ -262,7 +277,15 @@ export function runConfigure(
   for (const [key, entry] of Object.entries(program.appConfig.entries)) {
     const before = next[key];
     const current = resolved[key];
-    const { value, userTyped } = promptConfigKey(key, entry, current, true, fromSchema, hostEnv);
+    const { value, userTyped } = promptConfigKey(
+      key,
+      entry,
+      current,
+      true,
+      fromSchema,
+      hostEnv,
+      jsonSchema,
+    );
     if (value !== undefined && String(value).length > 0) {
       const storedInFile =
         key in existing &&

package/src/config/validate.test.ts

@@ -58,11 +58,52 @@ describe("config/validate", () => {
   });
 
   test("parseConfigSetValue requires --json for objects", () => {
-    expect(() => parseConfigSetValue('{"ttl":1}', { type: "object" }, rootSchema, false)).toThrow(
+    expect(() => parseConfigSetValue("ttl:1", { type: "object" }, rootSchema, false)).toThrow(
       /--json/,
     );
     expect(parseConfigSetValue('{"ttl":1}', { type: "object" }, rootSchema, true)).toEqual({
       ttl: 1,
     });
+    expect(parseConfigSetValue('{"ttl":1}', { type: "object" }, rootSchema, false)).toEqual({
+      ttl: 1,
+    });
+  });
+
+  test("parseConfigSetValue accepts comma-separated string arrays", () => {
+    const servicesSchema = {
+      type: "array",
+      items: { type: "string" },
+    };
+    expect(parseConfigSetValue("a,b", servicesSchema, rootSchema, false)).toEqual(["a", "b"]);
+    expect(parseConfigSetValue('["a","b"]', servicesSchema, rootSchema, false)).toEqual(["a", "b"]);
+  });
+
+  test("parseConfigSetValue accepts comma-separated number arrays", () => {
+    const schema = { type: "array", items: { type: "integer" } };
+    expect(parseConfigSetValue("1, 2, 3", schema, rootSchema, false)).toEqual([1, 2, 3]);
+  });
+
+  test("parseConfigSetValue accepts comma-separated date arrays", () => {
+    const schema = {
+      type: "array",
+      items: { type: "string", format: "date" },
+    };
+    expect(parseConfigSetValue("2024-01-01,2024-02-01", schema, rootSchema, false)).toEqual([
+      "2024-01-01",
+      "2024-02-01",
+    ]);
+  });
+
+  test("parseConfigSetValue rejects non-primitive arrays without JSON", () => {
+    const schema = {
+      type: "array",
+      items: {
+        type: "object",
+        properties: { ttl: { type: "number" } },
+        required: ["ttl"],
+      },
+    };
+    expect(() => parseConfigSetValue("a,b", schema, rootSchema, false)).toThrow(/--json/);
+    expect(parseConfigSetValue('[{"ttl":1}]', schema, rootSchema, false)).toEqual([{ ttl: 1 }]);
   });
 });

package/src/config/validate.ts

@@ -3,8 +3,16 @@ Draft-07 JSON Schema subset validator for program.appConfig files.
 Aligned with common ts-json-schema-generator output (local $ref, objects, scalars).
 */
 
+import { parseCommaList, parseDate, parseDateTime } from "../formats.ts";
+
 type JsonSchema = Record<string, unknown>;
 
+/** Homogeneous primitive `items` schema for comma-separated array input. */
+interface PrimitiveArrayItems {
+  kind: "string" | "integer" | "number" | "boolean";
+  format?: string;
+}
+
 export interface ValidateResult {
   valid: boolean;
   errors: string[];
@@ -247,6 +255,135 @@ function validateArray(
   }
 }
 
+function validateParsedConfigValue(
+  parsed: unknown,
+  propertySchema: JsonSchema | undefined,
+  rootSchema: JsonSchema,
+): unknown {
+  if (!propertySchema) {
+    return parsed;
+  }
+  const errors: string[] = [];
+  validateValue(parsed, propertySchema, rootSchema, "$", errors);
+  if (errors.length > 0) {
+    throw new Error(errors[0] ?? "Invalid config value");
+  }
+  return parsed;
+}
+
+function parseJsonLiteral(
+  raw: string,
+  propertySchema: JsonSchema | undefined,
+  rootSchema: JsonSchema,
+): unknown {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    throw new Error("Invalid JSON");
+  }
+  return validateParsedConfigValue(parsed, propertySchema, rootSchema);
+}
+
+function homogeneousPrimitiveArrayItems(
+  arraySchema: JsonSchema,
+  rootSchema: JsonSchema,
+): PrimitiveArrayItems | undefined {
+  const items = arraySchema.items;
+  if (typeof items !== "object" || items === null || Array.isArray(items)) {
+    return undefined;
+  }
+  const resolved = resolveSchema(items as JsonSchema, rootSchema);
+  if (!resolved) {
+    return undefined;
+  }
+  const types = normalizeTypes(resolved.type);
+  if (types.length !== 1) {
+    return undefined;
+  }
+  const kind = types[0];
+  if (kind === "string" || kind === "integer" || kind === "number" || kind === "boolean") {
+    const format = typeof resolved.format === "string" ? resolved.format : undefined;
+    return { kind, format };
+  }
+  return undefined;
+}
+
+function parseBooleanToken(raw: string): boolean {
+  const lower = raw.trim().toLowerCase();
+  if (lower === "true" || lower === "1") return true;
+  if (lower === "false" || lower === "0") return false;
+  throw new Error("Expected boolean: true, false, 1, or 0");
+}
+
+function parsePrimitiveArraySegment(segment: string, items: PrimitiveArrayItems): unknown {
+  switch (items.kind) {
+    case "string": {
+      if (items.format === "date") {
+        return parseDate(segment);
+      }
+      if (items.format === "date-time") {
+        return parseDateTime(segment);
+      }
+      return segment;
+    }
+    case "integer": {
+      const n = Number(segment);
+      if (Number.isNaN(n) || !Number.isInteger(n)) {
+        throw new Error(`Expected integer: ${segment}`);
+      }
+      return n;
+    }
+    case "number": {
+      const n = Number(segment);
+      if (Number.isNaN(n)) {
+        throw new Error(`Expected number: ${segment}`);
+      }
+      return n;
+    }
+    case "boolean":
+      return parseBooleanToken(segment);
+  }
+}
+
+function parseHomogeneousPrimitiveArray(
+  raw: string,
+  arraySchema: JsonSchema,
+  rootSchema: JsonSchema,
+): unknown[] {
+  const items = homogeneousPrimitiveArrayItems(arraySchema, rootSchema);
+  if (!items) {
+    throw new Error("Use --json for object or array config values");
+  }
+  const segments = parseCommaList(raw);
+  if (segments.length === 0) {
+    throw new Error("Comma-separated list must contain at least one value");
+  }
+  return segments.map((segment) => parsePrimitiveArraySegment(segment, items));
+}
+
+/** Optional suffix for interactive configure value prompts (schema-aware). */
+export function configValueInputHint(
+  propertySchema: JsonSchema | undefined,
+  rootSchema: JsonSchema,
+): string | undefined {
+  if (!propertySchema) {
+    return undefined;
+  }
+  const resolved = resolveSchema(propertySchema, rootSchema);
+  if (!resolved) {
+    return undefined;
+  }
+  const types = normalizeTypes(resolved.type);
+  if (types.includes("array") && homogeneousPrimitiveArrayItems(resolved, rootSchema)) {
+    return "comma-separated or JSON array";
+  }
+  if (types.includes("array") || types.includes("object")) {
+    return "JSON";
+  }
+  return undefined;
+}
+
 /** Parse a CLI/MCP set value against a property schema. */
 export function parseConfigSetValue(
   raw: string,
@@ -255,28 +392,22 @@ export function parseConfigSetValue(
   useJson: boolean,
 ): unknown {
   if (useJson) {
-    const parsed = JSON.parse(raw) as unknown;
-    const errors: string[] = [];
-    if (propertySchema) {
-      validateValue(parsed, propertySchema, rootSchema, "$", errors);
-      if (errors.length > 0) {
-        throw new Error(errors[0] ?? "Invalid config value");
-      }
-    }
-    return parsed;
+    return parseJsonLiteral(raw, propertySchema, rootSchema);
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    return parseJsonLiteral(trimmed, propertySchema, rootSchema);
   }
 
   const resolved = propertySchema ? resolveSchema(propertySchema, rootSchema) : undefined;
   const types = resolved ? normalizeTypes(resolved.type) : ["string"];
 
   if (types.includes("boolean")) {
-    const lower = raw.trim().toLowerCase();
-    if (lower === "true" || lower === "1") return true;
-    if (lower === "false" || lower === "0") return false;
-    throw new Error("Expected boolean: true, false, 1, or 0");
+    return parseBooleanToken(trimmed);
   }
   if (types.includes("number") || types.includes("integer")) {
-    const n = Number(raw);
+    const n = Number(trimmed);
     if (Number.isNaN(n)) {
       throw new Error("Expected number");
     }
@@ -285,7 +416,14 @@ export function parseConfigSetValue(
     }
     return n;
   }
-  if (types.includes("object") || types.includes("array")) {
+  if (types.includes("array")) {
+    if (!resolved) {
+      throw new Error("Use --json for object or array config values");
+    }
+    const parsed = parseHomogeneousPrimitiveArray(trimmed, resolved, rootSchema);
+    return validateParsedConfigValue(parsed, propertySchema, rootSchema);
+  }
+  if (types.includes("object")) {
     throw new Error("Use --json for object or array config values");
   }
   return raw;

package/examples/full-example/scripts/dev-formula.ts

@@ -1,54 +0,0 @@
-/** Backup, write, and restore the release formula for local dev Homebrew installs. */
-
-import { createHash } from "node:crypto";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { createIdentity } from "./create-identity.ts";
-import { renderDevFormula } from "./formula-shared.ts";
-
-const { key } = createIdentity;
-const root = join(import.meta.dir, "..");
-const stagingDir = join(root, "Formula", ".staging");
-const stagingPath = join(stagingDir, key);
-const formulaPath = join(root, "Formula", `${key}.rb`);
-const backupPath = join(stagingDir, `${key}.rb.bak`);
-
-/** Path to the committed release formula (`Formula/full-example.rb`). */
-export function releaseFormulaPath(): string {
-  return formulaPath;
-}
-
-/** Gitignored backup path used during `install-local`. */
-export function releaseFormulaBackupPath(): string {
-  return backupPath;
-}
-
-/** Copy the release formula to `.staging` before overwriting with the dev formula. */
-export function backupReleaseFormula(): void {
-  if (!existsSync(formulaPath)) {
-    return;
-  }
-  mkdirSync(stagingDir, { recursive: true });
-  copyFileSync(formulaPath, backupPath);
-}
-
-/** Restore the release formula from backup; no-op when no backup exists. */
-export function restoreReleaseFormula(): void {
-  if (!existsSync(backupPath)) {
-    return;
-  }
-  copyFileSync(backupPath, formulaPath);
-  unlinkSync(backupPath);
-}
-
-/** Stage `dist/full-example` and overwrite `Formula/full-example.rb` with a local `file://` dev formula. */
-export function writeDevFormula(): void {
-  const distPath = join(root, "dist", key);
-  mkdirSync(stagingDir, { recursive: true });
-  copyFileSync(distPath, stagingPath);
-  chmodSync(stagingPath, 0o755);
-
-  const sha256 = createHash("sha256").update(readFileSync(stagingPath)).digest("hex");
-  const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version as string;
-  writeFileSync(formulaPath, renderDevFormula(stagingPath, version, sha256), "utf8");
-}

package/examples/full-example/scripts/ensure-release-formula.ts

@@ -1,41 +0,0 @@
-#!/usr/bin/env bun
-/** Normalize `Formula/full-example.rb` to the release layout; recover from a leftover dev formula. */
-
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import {
-  releaseFormulaPath,
-  restoreReleaseFormula,
-  releaseFormulaBackupPath,
-} from "./dev-formula.ts";
-import { renderReleaseFormula } from "./formula-shared.ts";
-
-const formulaPath = releaseFormulaPath();
-const backupPath = releaseFormulaBackupPath();
-
-if (existsSync(backupPath)) {
-  restoreReleaseFormula();
-  console.log(`Restored release formula from ${backupPath}`);
-}
-
-let content = readFileSync(formulaPath, "utf8");
-if (content.includes("file://")) {
-  process.stderr.write(
-    `Dev formula still present at ${formulaPath}. Run: git restore ${formulaPath}\n`,
-  );
-  process.exit(1);
-}
-
-const version = content.match(/^\s*version\s+"([^"]+)"/m)?.[1];
-const sha256 = content.match(/^\s*sha256\s+"([^"]+)"/m)?.[1];
-if (!version || !sha256) {
-  process.stderr.write(`Could not parse version/sha256 from ${formulaPath}\n`);
-  process.exit(1);
-}
-
-const normalized = renderReleaseFormula(version, sha256);
-if (content !== normalized) {
-  writeFileSync(formulaPath, normalized, "utf8");
-  console.log(`Normalized ${formulaPath} (v${version})`);
-} else {
-  console.log(`Release formula OK: ${formulaPath} (v${version})`);
-}

package/examples/full-example/scripts/gen-dev-formula.ts

@@ -1,7 +0,0 @@
-#!/usr/bin/env bun
-/** Generate Formula/full-example.rb for local dev install (file:// URL). Prefer `with-dev-formula.ts` via `just install-local`. */
-
-import { releaseFormulaPath, writeDevFormula } from "./dev-formula.ts";
-
-writeDevFormula();
-console.log(`Wrote ${releaseFormulaPath()}`);