yarkr-cli 1.0.0 → 1.0.2

package/README.md

@@ -4,29 +4,61 @@ Install skills, agents and MCP toolsets from [Yarkr](https://yarkr.com) into the
 Claude Code, Codex, opencode, Cursor and more.
 
 ```sh
-npx yarkr-cli add posterus-ltd/code-review-checklist     # a public package, no account needed
-npx yarkr-cli add posterus-ltd/github --harness codex   # pick the harnesses to write
+npm install -g yarkr-cli                                 # Node 22 or newer; or run any command with `npx yarkr-cli …`
+yarkr add posterus-ltd/code-review-checklist            # a public package, no account needed
+yarkr add posterus-ltd/github --harness codex           # pick the harnesses to write
 ```
 
-In a project, `yarkr init` creates `yarkr.json`; `yarkr add` and `yarkr sync` then pin every package in `yarkr.lock`:
+## Sync an ark to your machine
+
+An ark is a curated set of skills, agents and toolsets hosted in the registry. `yarkr sync` writes each one into the
+harness's own layout (`~/.claude/skills/…`, `~/.agents/…`, MCP configs and so on):
+
+```sh
+yarkr arks                                    # list public arks
+yarkr sync acme/starter                       # install one into this folder
+yarkr sync acme/starter -g                    # …or into your home directory
+yarkr sync acme/starter --harness claude-code # only write Claude Code's files
+yarkr ark                                     # what your arks give you, and which version
+```
+
+Signed in, a bare `yarkr sync` installs every ark you're a member of, plus your personal ark. Run it again to pick up
+whatever an admin added or removed; `yarkr sync --check` exits 1 when you're behind.
+
+## Set up an existing repo
+
+In a project, `yarkr init` creates `yarkr.json` (and `.yarkrrc`), detecting the harnesses already used there.
+`yarkr add` and `yarkr sync` then pin every package in `yarkr.lock`, so teammates and CI get the same releases:
 
 ```sh
-npm install -g yarkr-cli
-yarkr init
+cd my-repo
+yarkr init --ark acme/engineering            # optional: install a team's ark into this project
 yarkr add posterus-ltd/playwright-test-authoring
-yarkr sync --check   # in CI: exit 1 when anything is out of date
+git add yarkr.json yarkr.lock .yarkrrc .claude AGENTS.md && git commit
+yarkr sync --check                           # in CI: exit 1 when anything is out of date
 ```
 
-Publishing from a repo? Yarkr finds `SKILL.md` folders, `agents/*.md` and `.mcp.json` on its own. Anything else
-(a skill that's a single markdown file, or a folder with a README instead of SKILL.md) goes in one `yarkr.index.yaml`
-at the root, and nothing has to move:
+To publish from the repo instead, there's nothing to init: Yarkr finds `SKILL.md` folders, `agents/*.md` and
+`.mcp.json` on its own. Anything else (a skill that's a single markdown file, or a folder with a README instead of
+SKILL.md) goes in one `yarkr.index.yaml` at the root, and nothing has to move. Lint it before you push:
 
 ```sh
+yarkr lint                                               # what will be published, and what the hub would refuse
+yarkr lint --strict                                      # in CI: fail on warnings too
 yarkr guide index-repo -o ~/.claude/skills/index-repo/   # a skill your agent uses to write the index
-yarkr lint                                               # what will be published, and what's wrong
 ```
 
-`yarkr` uses the public hub at `https://yarkr.com` unless you point it at your own instance with
-`yarkr login --registry <url>`. Node 22 or newer.
+## Sign in for private packages
+
+Public packages and public arks work signed out. Your org's private packages and arks need a token:
+
+```sh
+yarkr login                  # signs in in the browser; the token goes to your keychain (or ~/.yarkrrc)
+yarkr login --no-browser     # over SSH: open the printed link anywhere, then paste the token
+yarkr whoami                 # check who you're signed in as
+```
+
+In CI, store a read-only token as a secret and set `YARKR_TOKEN`. `yarkr` uses the public hub at `https://yarkr.com`
+unless you point it at your own instance with `yarkr login --registry <url>`.
 
 Docs: [docs/cli.md](https://github.com/posterus-ltd/yarkr-public/blob/main/docs/cli.md) · Source: [github.com/posterus-ltd/yarkr-public](https://github.com/posterus-ltd/yarkr-public) · MIT

package/dist/yarkr.js

@@ -41811,18 +41811,20 @@ async function context(flags = {}) {
   const cwd = process.cwd();
   const conn = await resolveConnection({ dir: cwd, registry: flags.registry });
   const api = new Api(conn);
-  const project = flags.user ? null : await loadProjectConfig(cwd, { required: false });
-  if (project) return { dir: cwd, config: project, conn, api, lock: await loadLock(cwd), userMode: false };
-  const dir = userStateDir();
+  const userMode = !!(flags.global || flags.user);
+  const dir = userMode ? userStateDir() : cwd;
   let config2 = await loadProjectConfig(dir, { required: false });
   if (!config2) {
-    const detected2 = detectHarnesses2(os5.homedir());
-    config2 = { channel: "stable", scope: "user", harnesses: detected2.length ? detected2 : ["claude-code"], packages: {}, arks: "auto" };
-    await mkdir3(dir, { recursive: true });
-    await saveProjectConfig(dir, config2);
-    ui.info(`No ${CONFIG_FILE} here, so yarkr installs your arks into your home directory (${config2.harnesses.join(", ")}). Settings: ${path5.join(dir, CONFIG_FILE)}.`);
+    const detected2 = detectHarnesses2(userMode ? os5.homedir() : cwd);
+    config2 = { channel: "stable", scope: userMode ? "user" : "project", harnesses: detected2.length ? detected2 : ["claude-code"], packages: {}, arks: "auto" };
+    if (!flags.dryRun && !flags.check && !flags.readOnly) {
+      await mkdir3(dir, { recursive: true });
+      await saveProjectConfig(dir, config2);
+      if (userMode) ui.info(`Installing your arks into your home directory (${config2.harnesses.join(", ")}). Settings: ${path5.join(dir, CONFIG_FILE)}.`);
+      else ui.info(`Created ${CONFIG_FILE} here for ${config2.harnesses.join(", ")}. Use -g to install into your home directory instead.`);
+    }
   }
-  return { dir, config: config2, conn, api, lock: await loadLock(dir), userMode: true };
+  return { dir, config: config2, conn, api, lock: await loadLock(dir), userMode };
 }
 async function sync(flags, update2, arkRefs = []) {
   const { dir, config: config2, conn, api, lock, userMode } = await context(flags);
@@ -42499,7 +42501,7 @@ async function mcpRemove(scopes, flags) {
   if (!flags.noSync) await sync(flags);
 }
 async function mcpList(flags) {
-  const { config: config2, conn } = await context(flags);
+  const { config: config2, conn } = await context({ ...flags, readOnly: true });
   const rows = (config2.mcp ?? []).map((m) => connectionFor(conn.server, m));
   if (flags.json) return console.log(JSON.stringify(rows, null, 2));
   if (!rows.length) {
@@ -45039,11 +45041,11 @@ async function repoLint(dir, opts) {
 }
 
 // src/index.ts
-var VERSION = true ? "1.0.0" : "0.0.0-dev";
+var VERSION = true ? "1.0.2" : "0.0.0-dev";
 var act = (fn) => async (...a) => {
   await fn(...a);
 };
-var syncFlags = (c) => c.option("--harness <ids...>", `limit to some harnesses (${HARNESS_IDS.join(", ")})`).option("--dry-run", "show what would change; write nothing").option("--check", "exit 1 if anything is out of date (for CI)").option("--force", "overwrite files edited locally").option("--require-signatures", "refuse unsigned releases").option("--user", "use your arks and home directory even inside a project").option("--registry <url>", "registry to use (default: from .yarkrrc)");
+var syncFlags = (c) => c.option("--harness <ids...>", `limit to some harnesses (${HARNESS_IDS.join(", ")})`).option("--dry-run", "show what would change; write nothing").option("--check", "exit 1 if anything is out of date (for CI)").option("--force", "overwrite files edited locally").option("--require-signatures", "refuse unsigned releases").option("-g, --global", "install into your home directory instead of this folder").addOption(new Option("--user").hideHelp()).option("--registry <url>", "registry to use (default: from .yarkrrc)");
 function buildProgram() {
   const program2 = new Command().name("yarkr").description("Yarkr: install your org's skills, agents and MCP configs into every harness.").version(VERSION).option("-q, --quiet", "only print warnings and errors").hook("preAction", (cmd) => {
     ui.quiet = !!cmd.opts().quiet;
@@ -45059,11 +45061,11 @@ function buildProgram() {
   program2.command("arks").description("list public arks: curated sets anyone can sync or connect over MCP").option("--json").action(act(publicArks));
   program2.command("lint").argument("[dir]", "a repo checkout", ".").description("check a repo is set up as a Yarkr source: what it publishes, problems the hub would refuse, and index typos or weak descriptions").option("--namespace <ns>", "namespace to show names in (default: the git owner)").option("--strict", "exit 1 on warnings too").option("--json").action(act(repoLint));
   program2.command("guide").argument("[name]", "a guide, e.g. create-ark; omit to list them").description("print instructions for your agent, e.g. how to build an ark for a topic").option("-o, --out <path>", "write to a file, or <dir>/SKILL.md for a directory (e.g. ~/.claude/skills/create-ark/)").option("--topic <topic>", "create-ark: what the ark is about").addOption(new Option("--type <type>", "create-ark: the kind of package it holds").choices(["skill", "agent", "mcp"])).action(act(guide));
-  syncFlags(program2.command("add").argument("<packages...>", "namespace/name[@range]").description("add packages to yarkr.json (outside a project: to your personal ark, or your user config when signed out) and sync").option("--no-sync", "only edit yarkr.json")).action(act((pkgs, o) => add(pkgs, { ...o, noSync: o.sync === false })));
+  syncFlags(program2.command("add").argument("<packages...>", "namespace/name[@range]").description("add packages to yarkr.json (with -g: to your personal ark, or your user config when signed out) and sync").option("--no-sync", "only edit yarkr.json")).action(act((pkgs, o) => add(pkgs, { ...o, noSync: o.sync === false })));
   syncFlags(program2.command("remove").argument("<packages...>", "packages, or arks listed in yarkr.json").description("remove packages or arks (or opt out of optional ark items) and delete their files").option("--no-sync", "only edit yarkr.json")).action(act((pkgs, o) => remove(pkgs, { ...o, noSync: o.sync === false })));
   syncFlags(program2.command("update").argument("[packages...]").description("move packages to the newest release their range allows")).action(act((pkgs, o) => update(pkgs, o)));
   syncFlags(
-    program2.command("sync").argument("[arks...]", "arks to add first: <org>/<ark>, yours or another org's public ark (which needs no sign-in)").description("install locked releases into each harness's native layout (outside a project: your arks, into your home directory)")
+    program2.command("sync").argument("[arks...]", "arks to add first: <org>/<ark>, yours or another org's public ark (which needs no sign-in)").description("install locked releases into each harness's native layout in this folder (with -g: your home directory)")
   ).action(act((refs, o) => sync(o, void 0, refs)));
   program2.command("yank").argument("<release>", "namespace/name@version").description("yank a release (org admins): ranges and stable skip it, exact pins still install it").option("--reason <text>", "why, shown to everyone who installed it").option("--undo", "un-yank it").action(act(yank));
   program2.command("diff").argument("[package]").description("show local edits to synced files").option("--name-only").action(act(diff));
@@ -45086,7 +45088,7 @@ function buildProgram() {
     act((scopes, o) => mcpAdd(scopes, { ...o, noSync: o.sync === false }))
   );
   mcpFlags(mcp.command("remove").argument("<scopes...>").description("remove MCP connections from every harness")).action(act((scopes, o) => mcpRemove(scopes, { ...o, noSync: o.sync === false })));
-  mcp.command("list").description("show configured MCP connections").option("--user", "your user config even inside a project").option("--json").action(act((o) => mcpList(o)));
+  mcp.command("list").description("show configured MCP connections").option("-g, --global", "your user config instead of this folder's").addOption(new Option("--user").hideHelp()).option("--json").action(act((o) => mcpList(o)));
   program2.command("mcp-config").argument("<harness>", HARNESS_IDS.join(" | ")).description("print the config that connects a harness to Yarkr's MCP server").option("--token-env <name>", "environment variable holding the token", "YARKR_TOKEN").option("--registry <url>").action(act(mcpConfig));
   return program2;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarkr-cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Install skills, agents and MCP toolsets from Yarkr into Claude Code, Codex, opencode, Cursor and more",
   "license": "MIT",
   "homepage": "https://yarkr.com",
@@ -47,8 +47,8 @@
     "typescript": "~5.9.3",
     "vitest": "^3.2.4",
     "yaml": "^2.8.1",
-    "@yarkr/core": "0.1.0",
     "@yarkr/evals": "0.1.0",
+    "@yarkr/core": "0.1.0",
     "@yarkr/schema": "0.1.0"
   },
   "scripts": {