@ajaykumarnpm/talea 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-09-22
+
+### Breaking
+- `talea pick <repo>` keeps one repo; `talea update` upgrades the CLI
+
+## [0.5.0] - 2026-09-22
+
+### Added
+- run commands from outside a workspace
+
 ## [0.4.0] - 2026-09-22
 
 ### Added

package/README.md

@@ -46,6 +46,9 @@ talea manifest push          # publish the catalogue so the next machine can rea
 repos, every org you belong to, and anything shared with you directly. It then
 asks what this machine should keep and fills the tree.
 
+Every command works from anywhere after that. Outside the workspace it uses
+the one `init` made; with more than one on the machine, it asks which.
+
 ## Every machine after that
 
 ```sh
@@ -63,6 +66,7 @@ talea sync                   # clone the new, fast-forward the rest
 talea status                 # branch, clean/dirty, ahead/behind, in one table
 talea add some-repo          # keep one more on this machine, and clone it now
 talea select                 # reopen the checklist and change the whole list
+talea pick some-repo          # keep that one — an unknown name opens the checklist
 cd $(talea where eklavya)
 ```
 
@@ -164,7 +168,7 @@ Treat the id like a bookmark you would not paste into a public channel.
 | `talea clone` | clone only — never fetches or merges |
 | `talea adopt` | move checkouts you already have into place |
 | `talea status` | branch, clean/dirty, ahead/behind |
-| `talea select` | reopen the checklist — what this machine keeps |
+| `talea select` | reopen the checklist — `talea pick <repo>` for one |
 | `talea add` / `talea rm` | change that one repo at a time |
 | `talea where <repo>` | print a repo's path, for `cd $( )` |
 | `talea list` | the catalogue |
@@ -173,7 +177,7 @@ Treat the id like a bookmark you would not paste into a public channel.
 | `talea manifest push/pull` | move the catalogue between machines |
 | `talea skill` | install the skill that lets your coding agent drive talea |
 | `talea doctor` | check this machine can do the work |
-| `talea upgrade` | update the CLI itself |
+| `talea upgrade` | update the CLI itself (also `talea update`) |
 
 Every one of them takes `-g <group>` and `-r <repo>` to narrow the run, and
 `--help` for its own examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ajaykumarnpm/talea",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "One folder structure for every machine. Clone, adopt and sync your GitHub repos from a manifest you own.",
   "type": "module",
   "bin": {

package/skills/talea/SKILL.md

@@ -46,6 +46,10 @@ It exits **non-zero** on an unknown name and writes every diagnostic to stderr,
 so `cd "$(talea where typo)"` fails instead of landing in the home directory.
 Never `cd` to a path it did not print.
 
+Outside a workspace it falls back to the ones this machine has. With several
+and no terminal — which is how you run it — it lists them and exits non-zero.
+`cd` into the workspace the user means rather than guessing from the list.
+
 Two owners can own a repo of the same name. When that happens it says so and
 exits non-zero — pass `owner/name` rather than picking one.
 
@@ -113,11 +117,17 @@ and nothing in talea will do it for them.
 talea add some-repo     # keep one more here, and clone it now
 talea rm some-repo      # stop keeping it — the checkout stays exactly where it is
 talea select            # reopen the whole checklist, interactively
+talea pick some-repo    # = add when the name is exact; otherwise the checklist
 ```
 
 `talea select` needs a terminal. In a non-interactive session it prints a
 summary instead of hanging, so prefer `add` and `rm` when acting on the
 developer's behalf and leave `select` as something to suggest they run.
+`pick <name>` falls back to that same checklist on a typo, so an agent uses
+`add`, which fails loudly instead.
+
+`talea update` reinstalls the CLI (it is `upgrade`), not `sync`. Never run it
+to refresh repos.
 
 `rm` does **not** delete the checkout. Say that plainly when you run it, or it
 reads like data loss.

package/src/cli.js

@@ -52,7 +52,6 @@ const ALIASES = {
   setup: 'init',
   bootstrap: 'init',
   pull: 'sync',
-  update: 'sync',
   refresh: 'discover',
   pick: 'select',
   choose: 'select',
@@ -63,6 +62,7 @@ const ALIASES = {
   run: 'exec',
   skills: 'skill',
   remove: 'rm',
+  update: 'upgrade',
   'self-update': 'upgrade',
 };
 
@@ -110,7 +110,7 @@ ${c.bold('Commands')}
   ${c.cyan('clone')}      clone only — never fetches or merges
   ${c.cyan('adopt')}      move repos you already have into the right place
   ${c.cyan('status')}     one table: branch, clean/dirty, ahead/behind
-  ${c.cyan('select')}     reopen the checklist — what this machine keeps
+  ${c.cyan('select')}     reopen the checklist — or ${c.dim('talea pick <repo>')} for one
   ${c.cyan('add')}        keep another repo on this machine (${c.dim('rm')} to drop one)
   ${c.cyan('where')}      print a repo's path — ${c.dim('cd $(talea where eklavya)')}
   ${c.cyan('list')}       show the catalogue

package/src/commands/add.js

@@ -34,12 +34,17 @@ Options
   -j, --jobs <n>        parallel clones
 `;
 
-/** Resolve `name` or `owner/name` against the catalogue, or exit saying why. */
-export function resolve(manifest, name) {
+/** Every catalogue entry `name` or `owner/name` could mean, ignoring case. */
+export function lookup(manifest, name) {
   const wanted = String(name).toLowerCase();
-  const matches = manifest.repos.filter(
+  return manifest.repos.filter(
     (r) => r.name.toLowerCase() === wanted || `${r.owner}/${r.name}`.toLowerCase() === wanted,
   );
+}
+
+/** Resolve `name` or `owner/name` against the catalogue, or exit saying why. */
+export function resolve(manifest, name) {
+  const matches = lookup(manifest, name);
 
   if (!matches.length) {
     fail(`No repo called "${name}" in the catalogue.`);
@@ -54,7 +59,7 @@ export function resolve(manifest, name) {
 }
 
 export async function run(opts, positionals = []) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   requireCatalogue(manifest);
 
   if (!positionals.length) {

package/src/commands/adopt.js

@@ -322,7 +322,7 @@ export function parseFromPaths(from) {
 }
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
 
   if (opts['fix-paths']) {
     heading('Repairing paths for repos already adopted');

package/src/commands/clone.js

@@ -200,7 +200,7 @@ export function writeDocs(manifest, root, repos) {
 }
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   requireCatalogue(manifest);
 
   const protocol = opts.protocol ?? state.protocol ?? 'ssh';

package/src/commands/exec.js

@@ -46,7 +46,7 @@ export async function run(opts, positionals) {
     process.exit(1);
   }
 
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
   const entries = clonedOnly(withPaths(manifest, root, selectRepos(manifest, opts, pool)));
 

package/src/commands/init.js

@@ -15,6 +15,7 @@ import { samePath } from '../adopt.js';
 import { c, context, fail, heading, info, ok, plain, skip, warn } from '../log.js';
 import { run as discover } from './discover.js';
 import { run as sync } from './sync.js';
+import { rememberWorkspace } from '../workspace.js';
 
 export const help = `
 ${c.bold('talea init')} — set this machine up
@@ -105,6 +106,8 @@ export async function run(opts, positionals = []) {
   } else {
     skip(`${STATE_FILE} already here, leaving it alone`);
   }
+  // So `talea sync` run from outside any workspace knows this one exists.
+  rememberWorkspace(target);
 
   let manifest = loadManifest(target);
 

package/src/commands/select.js

@@ -9,9 +9,10 @@
 // because `clone` and `sync` ask the same question, and the cloning is
 // `clone.run`, re-entered after the new selection is on disk.
 
-import { c, fail, heading, ok, plain, skip } from '../log.js';
+import { c, fail, heading, ok, plain, skip, warn } from '../log.js';
 import { chooseRepos } from '../select.js';
 import { machineRepos, requireCatalogue, requireWorkspace } from '../workspace.js';
+import * as add from './add.js';
 import * as clone from './clone.js';
 
 export const help = `
@@ -19,6 +20,8 @@ ${c.bold('talea select')} — change what this machine keeps
 
   ${c.dim('talea select')}              reopen the checklist, then clone what is newly ticked
   ${c.dim('talea select --no-clone')}   change the list only, fill it in later
+  ${c.dim('talea pick PiDom')}          keep that one repo and clone it — or, if no repo
+                            has that name, open the checklist instead
 
 The checklist opens with the current selection ticked. Space toggles, Enter
 saves, Esc cancels and changes nothing. Everything in the catalogue is listed,
@@ -29,7 +32,10 @@ It writes ${c.dim('.talea.json')}, which never leaves this machine, so no other
 selection changes. Unticking a repo takes it off the list and leaves the
 checkout exactly where it is; deleting it is your call.
 
-For one repo, ${c.dim('talea add <repo>')} and ${c.dim('talea rm <repo>')} skip the checklist.
+A name that matches exactly one repo (case does not matter, ${c.dim('owner/name')} works)
+is ${c.dim('talea add <repo>')}. A name that matches none, or two owners' repos, opens the
+checklist, because a typo should land you in the list rather than nowhere.
+${c.dim('talea rm <repo>')} takes one off.
 
 Options
       --no-clone        save the selection, clone nothing
@@ -37,6 +43,11 @@ Options
   -j, --jobs <n>        parallel clones
 `;
 
+/** The names that do not pin down exactly one repo — empty means every one does. */
+export function unresolved(manifest, names) {
+  return names.filter((n) => add.lookup(manifest, n).length !== 1);
+}
+
 /** What changed, as two lists of names. Pure, so it can be tested. */
 export function changes(before, after) {
   const had = new Set(before);
@@ -47,8 +58,8 @@ export function changes(before, after) {
   };
 }
 
-export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+export async function run(opts, positionals = []) {
+  const { root, manifest, state } = await requireWorkspace();
   requireCatalogue(manifest);
 
   // -g/-r narrow a run; they cannot narrow a decision about the whole machine.
@@ -60,6 +71,12 @@ export async function run(opts) {
     process.exit(1);
   }
 
+  if (positionals.length) {
+    const missing = unresolved(manifest, positionals);
+    if (!missing.length) return add.run({ ...opts, removing: false }, positionals);
+    warn(`No single repo called ${missing.map((n) => `"${n}"`).join(', ')} — opening the checklist.`);
+  }
+
   const before = machineRepos(manifest, state).map((r) => r.name);
   const { repos } = await chooseRepos({ manifest, root, state, opts: { ...opts, pick: true } });
   const after = repos.map((r) => r.name);

package/src/commands/status.js

@@ -29,7 +29,7 @@ Options
 `;
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
   const entries = withPaths(manifest, root, selectRepos(manifest, opts, pool));
 

package/src/commands/sync.js

@@ -31,6 +31,9 @@ your default set, or a checklist of everything in the catalogue with those
 defaults already ticked. The answer is remembered in ${c.dim('.talea.json')}, so every run
 after that is a bare ${c.dim('talea sync')}.
 
+It runs from anywhere. Inside a workspace it uses that one; outside, it uses
+the workspace ${c.dim('talea init')} made, or asks which when this machine has several.
+
 Options
   -g, --group <names>   comma-separated groups
   -r, --repo <names>    comma-separated repo names
@@ -53,7 +56,7 @@ leaves it alone, and says which.
 `;
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   requireCatalogue(manifest);
 
   const protocol = opts.protocol ?? state.protocol ?? 'ssh';

package/src/commands/tree.js

@@ -30,8 +30,8 @@ Options
 
 const hasDoc = (dir) => existsSync(path.join(dir, 'CLAUDE.md'));
 
-export function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+export async function run(opts) {
+  const { root, manifest, state } = await requireWorkspace();
   const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
   const entries = withPaths(manifest, root, selectRepos(manifest, opts, pool));
 

package/src/commands/upgrade.js

@@ -6,6 +6,7 @@ export const help = `
 ${c.bold('talea upgrade')} — update the CLI itself
 
   ${c.dim('talea upgrade')}                    reinstall from npm at the latest version
+  ${c.dim('talea update')}                     the same thing
   ${c.dim('talea upgrade --check')}            only report whether one is available
   ${c.dim('talea upgrade --on')}               turn the daily update notice on
   ${c.dim('talea upgrade --off')}              turn the daily update notice off

package/src/commands/where.js

@@ -17,10 +17,13 @@ composes with ${c.dim('cd')}, ${c.dim('code')}, ${c.dim('open')} and anything el
 
 Exits non-zero if the repo is not in the catalogue, so ${c.dim('cd $(talea where typo)')}
 fails loudly instead of landing you in your home directory.
+
+Works from outside a workspace too: with one on this machine it uses that, with
+several it asks — on stderr, so the answer never ends up in the path.
 `;
 
-export function run(opts, positionals = []) {
-  const { root, manifest } = requireWorkspace();
+export async function run(opts, positionals = []) {
+  const { root, manifest } = await requireWorkspace();
   const name = positionals[0];
 
   if (!name) {

package/src/config.js

@@ -33,7 +33,7 @@ export const USER_STATE = path.join(USER_DIR, 'state.json');
 
 const readJson = (file) => JSON.parse(readFileSync(file, 'utf8'));
 
-/** Machine-wide state: the update-check stamp, the gist id. Not per workspace. */
+/** Machine-wide state: the update-check stamp, the gist id, the workspace list. Not per workspace. */
 export function readUserState() {
   try {
     return readJson(USER_STATE);
@@ -48,7 +48,8 @@ export function writeUserState(state) {
     writeFileSync(USER_STATE, JSON.stringify(state, null, 2) + '\n');
   } catch {
     // A read-only home directory must not break the actual command. The only
-    // things kept here are a cache stamp and a gist id.
+    // things kept here are a cache stamp, a gist id and the workspace list,
+    // and a lost list re-fills itself the next time a command runs inside one.
   }
 }
 
@@ -95,6 +96,19 @@ export function findWorkspace(start = process.cwd()) {
   }
 }
 
+/**
+ * Every workspace this machine has set up, as recorded in ~/.talea/state.json.
+ *
+ * This is what lets `talea sync` run from anywhere: outside a workspace the
+ * upward walk finds nothing, and this list is what is left to ask. Kept in the
+ * machine-wide state rather than the catalogue because a path on this laptop
+ * means nothing on the next one. Entries whose .talea.json has gone are skipped
+ * on read, not dropped on write — a deleted workspace stops being offered, but
+ * an unplugged drive that comes back has not been forgotten.
+ */
+export const knownWorkspaces = () =>
+  (readUserState().workspaces ?? []).filter((dir) => existsSync(path.join(dir, STATE_FILE)));
+
 export function loadState(workspaceRoot) {
   const file = path.join(workspaceRoot, STATE_FILE);
   return existsSync(file) ? readJson(file) : {};

package/src/workspace.js

@@ -4,9 +4,25 @@
 // Every command that acts on repos goes through here, so `clone`, `sync`,
 // `status` and `exec` filter identically.
 
-import { findWorkspace, loadManifest, loadState, repoDir, repoGroup } from './config.js';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+
+import { samePath } from './adopt.js';
+import {
+  STATE_FILE,
+  findWorkspace,
+  knownWorkspaces,
+  loadManifest,
+  loadState,
+  readUserState,
+  repoDir,
+  repoGroup,
+  writeUserState,
+} from './config.js';
 import { isRepo } from './git.js';
-import { fail } from './log.js';
+import { c, fail } from './log.js';
 
 const csv = (v) =>
   (Array.isArray(v) ? v : [v])
@@ -16,16 +32,87 @@ const csv = (v) =>
     .filter(Boolean);
 
 /**
- * Resolve the workspace, manifest and state, or exit with a useful message.
- * Commands that need an initialised workspace call this first.
+ * Add a workspace to this machine's list, once.
+ *
+ * Compared with samePath, not as strings: on macOS and Windows `~/workspace`
+ * and `~/Workspace` are one folder, and cd-ing in with the other spelling would
+ * otherwise add it again on every run.
+ */
+export function rememberWorkspace(root) {
+  const state = readUserState();
+  const list = state.workspaces ?? [];
+  if (list.some((dir) => samePath(dir, root))) return;
+  writeUserState({ ...state, workspaces: [...list, root] });
+}
+
+/**
+ * The workspaces a command run from outside any of them could mean: every one
+ * `init` has recorded, plus the default `~/Workspace` — which is how a
+ * workspace made before the list existed is still found from anywhere.
  */
-export function requireWorkspace() {
-  const root = findWorkspace();
-  if (!root) {
+export function workspaceCandidates(known = knownWorkspaces(), manifest = loadManifest(null)) {
+  const fallback = path.join(os.homedir(), manifest.workspace || 'Workspace');
+  const all = existsSync(path.join(fallback, STATE_FILE)) ? [...known, fallback] : known;
+  return all.filter((dir, i) => all.findIndex((d) => samePath(d, dir)) === i);
+}
+
+/**
+ * Outside a workspace: one known workspace is used, several are asked about.
+ *
+ * Everything here goes to stderr — `cd $(talea where)` reads stdout, and a
+ * prompt or a note there is a folder the shell tries to enter. With no
+ * terminal to ask on, it stops rather than picks: a script that syncs whichever
+ * workspace happened to be first is running against a tree nobody named.
+ */
+async function pickKnownWorkspace() {
+  const found = workspaceCandidates();
+
+  if (!found.length) {
     fail('Not inside a talea workspace (no .talea.json found).');
     console.error('\n  Run `talea init` to create one, or cd into an existing workspace.');
     process.exit(1);
   }
+  if (found.length === 1) {
+    console.error(c.dim(`Using the workspace at ${found[0]}\n`));
+    return found[0];
+  }
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    fail(`Not inside a talea workspace, and this machine has ${found.length}.`);
+    for (const dir of found) console.error(`    ${c.bold(dir)}`);
+    console.error('\n  cd into the one you mean.');
+    process.exit(1);
+  }
+
+  console.error(`\n${c.bold('Which workspace?')}`);
+  found.forEach((dir, i) => console.error(`  ${c.cyan(String(i + 1))}  ${dir}`));
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  const answer = (await rl.question(`\n${c.dim(`[1-${found.length}]`)} `)).trim();
+  rl.close();
+
+  // A wrong answer stops, same as a typo'd repo name: guessing here would run
+  // a bulk command against a tree the developer did not choose.
+  const chosen = found[Number(answer) - 1];
+  if (!/^\d+$/.test(answer) || !chosen) {
+    fail(`"${answer}" is not one of 1-${found.length}.`);
+    process.exit(1);
+  }
+  console.error('');
+  return chosen;
+}
+
+/**
+ * Resolve the workspace, manifest and state, or exit with a useful message.
+ * Commands that need an initialised workspace call this first.
+ *
+ * Inside a workspace the upward walk wins, exactly as git's does. Outside one,
+ * the workspaces this machine knows about are offered instead.
+ */
+export async function requireWorkspace() {
+  const inside = findWorkspace();
+  // Recorded on every run from inside, so a workspace made before the list
+  // existed joins it the first time anything is run there.
+  if (inside) rememberWorkspace(inside);
+  const root = inside ?? (await pickKnownWorkspace());
   const manifest = loadManifest(root);
   const state = loadState(root);
   return { root, manifest, state };