@ajaykumarnpm/talea 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.4.0] - 2026-09-22
+
+### Added
+- talea skill, and the CLI in the design system's palette
+
+### Fixed
+- **test**: skill.test.js asserted LF against a CRLF checkout
+- **test**: init.test.js depended on the author's own GitHub auth
+- create group folders only when cloning
+
+### Documentation
+- the site and the manual, at talea-run.web.app
+
 ## [0.3.0] - 2026-09-21
 
 ### Added

package/README.md

@@ -2,6 +2,8 @@
 
 **One folder structure for every machine you work on.**
 
+[talea-run.web.app](https://talea-run.web.app) — the site, and [the manual](https://talea-run.web.app/docs/).
+
 You have a laptop, a desktop, and a work machine. On each one, the repo you want
 is either missing or somewhere you have to go and find. `talea` fixes that: one
 catalogue of your GitHub repos, one tree, and a command that makes any machine
@@ -64,6 +66,21 @@ talea select                 # reopen the checklist and change the whole list
 cd $(talea where eklavya)
 ```
 
+## Let your coding agent do it
+
+```sh
+talea skill install
+```
+
+Installs a skill into Claude Code at **user scope**, so every project you open
+has it. After that `"where is eklavya?"` and `"my repos are scattered, tidy them
+up"` reach the right command — with the guardrails attached: an adopt is always
+shown as a dry run first, `--loose` is never taken on your behalf, and a removal
+is reported as *taken off the list* rather than as a delete.
+
+`talea skill` says whether it is installed, `talea skill uninstall` takes it back
+out, and it refuses to overwrite a skill called `talea` that talea did not write.
+
 ---
 
 ## The repos you already have
@@ -154,6 +171,7 @@ Treat the id like a bookmark you would not paste into a public channel.
 | `talea tree` | the folder tree on disk |
 | `talea exec -- <cmd>` | run one command in every repo |
 | `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 |
 
@@ -195,6 +213,14 @@ node bin/talea.js --help
 
 Tests run on macOS, Linux and Windows across Node 20, 22 and 24 on every push.
 
+The website lives in `web/` and is its own thing — Astro, deployed to Firebase
+Hosting on a push to `main` that touches it. `web/CLAUDE.md` is how to work on
+it.
+
+```sh
+cd web && npm install && npm run dev
+```
+
 ## Licence
 
 MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ajaykumarnpm/talea",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "One folder structure for every machine. Clone, adopt and sync your GitHub repos from a manifest you own.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "bin",
     "src",
     "manifest",
+    "skills",
     "templates",
     "README.md",
     "CHANGELOG.md"

package/skills/talea/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: talea
+description: "Operate talea, the CLI that gives every machine the same folder structure for its GitHub repos. Use when the user asks where a repo is, to clone or sync or pull their repos, to tidy or reorganise a workspace, to adopt checkouts that are in the wrong place, to change what this machine keeps, or to move their repo catalogue to another machine. Also use before running a command in several repos at once. Do not use for ordinary git work inside one repo that is already checked out."
+---
+
+<!-- talea-skill: installed by `talea skill install`; edits are overwritten -->
+
+# talea
+
+`talea` keeps one folder structure across every machine a developer works on.
+It holds a catalogue of their GitHub repos, moves checkouts they already have
+into place, clones what is missing, and fast-forwards the rest.
+
+Two rules make it safe to hand to an agent: it never pushes, and it never
+deletes. Everything below leans on that.
+
+## Find the binary first
+
+```bash
+command -v talea
+```
+
+That prints the path, or nothing. It is installed with
+`npm install -g @ajaykumarnpm/talea` — the package is scoped, the command is
+not. If it prints nothing, fall back to `npx -y @ajaykumarnpm/talea <command>`,
+which downloads on first use. If that fails too, say talea is not installed and
+give the one install command rather than guessing at a path.
+
+Shell variables do not survive between tool calls, so write the resolved path
+into every later command rather than setting `T=` and hoping.
+
+Everything below writes `talea` for readability. Substitute whatever the line
+above resolved to.
+
+## Where is this repo?
+
+This is the command to reach for most, and the reason the tool exists.
+
+```bash
+talea where eklavya          # the absolute path, one line, nothing else
+cd "$(talea where eklavya)"  # what it is actually for
+talea where                  # the workspace root
+```
+
+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.
+
+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.
+
+## Read before you write
+
+None of these change anything on disk. Run one before proposing work.
+
+| Command | Answers |
+|---|---|
+| `talea status` | branch, clean or dirty, ahead or behind, for every repo this machine keeps |
+| `talea list` | the catalogue — every repo, its group, its folder |
+| `talea tree` | the folder tree as it actually is on disk |
+| `talea doctor` | can this machine do the work: git, SSH, GitHub auth, the workspace |
+| `talea adopt` | what a move *would* do. It changes nothing without `--apply` |
+
+`talea status` is the one to run before suggesting a sync — a dirty repo is
+skipped, and saying so up front is better than reporting it afterwards.
+
+## Bringing a machine into line
+
+```bash
+talea sync                   # clone what is missing, fast-forward what is there
+talea clone                  # clone only — never fetches or merges
+talea sync -g NonStop        # one group
+talea sync -r eklavya        # one repo
+```
+
+`sync` is safe to run unattended. It fast-forwards **the branch you are on** and
+leaves anything else alone with a line saying why. It never switches branches,
+never merges a divergence and never pushes.
+
+Every bulk command exits non-zero if **any** repo failed, so check the exit
+code — the per-repo errors are printed but the run keeps going.
+
+## Adoption: the one that moves things
+
+A repo the developer already has, in the wrong folder, is **moved** into place
+rather than re-cloned. A move keeps branches, stashes, the reflog and
+uncommitted work; a re-clone throws all of it away.
+
+```bash
+talea adopt                    # show what would move, change nothing
+talea adopt --from ~/Desktop   # look there too; the folder is remembered
+talea adopt --apply            # do it
+```
+
+**Always run it without `--apply` first and show the developer the plan.** A
+move relocates directories they may have open in an editor, a terminal or a
+long-running process.
+
+Matching is on the **git remote URL**, not the folder name. When only the name
+matches — a fork, a mirror, an SDK cache — it is listed and left alone. `--loose`
+or `-r <repo>` includes it. Do not reach for `--loose` on the developer's behalf:
+the guard exists because an FVM Flutter SDK cache reports `origin` as
+`flutter/flutter` and name-matches a personal fork, and adopting it breaks every
+Flutter project on the machine.
+
+A second copy of the same repo is **parked** in `.talea-duplicates/`, not
+deleted. Say so when it happens — clearing that folder is the developer's call,
+and nothing in talea will do it for them.
+
+## What this machine keeps
+
+```bash
+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 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.
+
+`rm` does **not** delete the checkout. Say that plainly when you run it, or it
+reads like data loss.
+
+## Running one command everywhere
+
+```bash
+talea exec -- git status --short
+talea exec -g NonStop -- npm test
+```
+
+Everything after `--` runs in each repo. Treat it as you would any command run
+in N repositories at once: read-only commands freely, anything that writes only
+when the developer asked for it by name.
+
+## Moving the catalogue between machines
+
+```bash
+talea manifest push            # publish it; prints a gist id
+talea manifest pull <gist-id>  # on the next machine
+```
+
+The gist is **private**, but it still carries the names of private
+repositories. Treat the id as something not to paste into a public channel, and
+do not print it into a message that is going somewhere shared.
+
+The split that matters: the **catalogue** travels, the **selection** does not.
+Pulling it onto a new laptop hands over the full list to choose from, never the
+last machine's choices. So `manifest pull` alone changes nothing about what is
+cloned — `talea init` or `talea select` after it is what fills the tree.
+
+## Narrowing any run
+
+Every command takes `-g <group>` and `-r <repo>`, both repeatable, and `--help`
+for its own examples. An unknown group or repo name **exits non-zero** rather
+than quietly doing nothing, so a typo is loud.
+
+## Rules
+
+- **Never `--apply` an adopt the developer has not seen the dry run of.**
+- **Never `--loose`** unless they have looked at the name-only matches and said
+  which one they want.
+- Report a move as *moved*, a removal as *taken off the list*, and a duplicate
+  as *parked*. Those are three different things and the words are the whole
+  safety story.
+- Do not add `ignore: true` to a catalogue entry to work around a conflict
+  without saying so — it means another tool owns that checkout, and every talea
+  command will skip it from then on.
+- talea never pushes. If a repo is ahead of its remote, report it and stop;
+  pushing is the developer's call and not talea's job.
+- A bulk command that exits non-zero has a failed repo in it. Read the output
+  for the failures rather than reporting the run as done.

package/src/cli.js

@@ -20,6 +20,7 @@ import * as manifest from './commands/manifest.js';
 import * as doctor from './commands/doctor.js';
 import * as exec from './commands/exec.js';
 import * as upgrade from './commands/upgrade.js';
+import * as skill from './commands/skill.js';
 import { notifyIfOutdatedAsync } from './update.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -41,6 +42,7 @@ const COMMANDS = {
   manifest,
   doctor,
   exec,
+  skill,
   upgrade,
 };
 
@@ -59,6 +61,7 @@ const ALIASES = {
   cd: 'where',
   path: 'where',
   run: 'exec',
+  skills: 'skill',
   remove: 'rm',
   'self-update': 'upgrade',
 };
@@ -115,6 +118,7 @@ ${c.bold('Commands')}
   ${c.cyan('exec')}       run one command in every repo
   ${c.cyan('manifest')}   push or pull the catalogue through a private gist
   ${c.cyan('doctor')}     check git, SSH, GitHub auth and workspace health
+  ${c.cyan('skill')}      install the skill that lets your coding agent drive talea
   ${c.cyan('upgrade')}    update the CLI itself
 
 ${c.bold('A new machine')}
@@ -130,6 +134,9 @@ ${c.bold('Every day')}
   talea sync                    ${c.dim('# clone the new, fast-forward the rest')}
   talea status --drift          ${c.dim('# what is not where I left it')}
 
+${c.bold('With an agent')}
+  talea skill install           ${c.dim('# then ask Claude Code "where is eklavya?"')}
+
 ${c.bold('Common options')}
   -g, --group <names>   restrict to groups, e.g. -g nonstopio
   -r, --repo <names>    restrict to repos, e.g. -r eklavya

package/src/commands/init.js

@@ -7,14 +7,11 @@ import {
   STATE_FILE,
   expandHome,
   findWorkspace,
-  groupDir,
   loadManifest,
-  loadState,
   repoGroup,
   saveState,
 } from '../config.js';
 import { samePath } from '../adopt.js';
-import { machineRepos } from '../workspace.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';
@@ -129,13 +126,13 @@ export async function run(opts, positionals = []) {
     ['groups', `${groups.length}`],
   ]);
 
-  // The group folders for the repos this machine will actually hold — not one
-  // per owner in the catalogue. A collaborator repo you never clone should not
-  // leave an empty folder in the tree forever.
-  const mine = machineRepos(manifest, loadState(target));
-  for (const g of new Set(mine.map((r) => repoGroup(r)))) {
-    mkdirSync(path.join(target, groupDir(manifest, g)), { recursive: true });
-  }
+  // No group folders are created here. `init` runs before the picker — the
+  // checklist lives in `sync` — so anything made at this point is made from the
+  // catalogue's defaults, which is every owner the discovery found. Picking
+  // four repos out of 228 then left 18 empty owner folders in the tree, and an
+  // empty folder is indistinguishable from a checkout somebody deleted.
+  // `cloneMissing` creates the parent of each repo it is about to clone, so the
+  // only folders that ever appear are the ones with something in them.
 
   if (opts.clone === false) {
     plain(`\n${c.dim('Workspace ready. Run `talea sync` when you want the repos.')}`);

package/src/commands/skill.js

@@ -0,0 +1,142 @@
+// `talea skill` — put the agent-facing skill in the user's Claude Code.
+//
+// The skill is a single Markdown file describing how to drive this CLI safely:
+// which commands read, which move things, and which two flags must never be
+// reached for on somebody's behalf. Installing it at **user scope**
+// (`~/.claude/skills/`) rather than in a repo is the point — the developer has
+// one workspace across every project, so the agent needs the same instructions
+// in all of them.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { c, fail, heading, info, ok, plain, warn } from '../log.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+/** The copy that ships in the package. */
+export const source = path.join(here, '..', '..', 'skills', 'talea', 'SKILL.md');
+
+/**
+ * Claude Code reads user-scope skills from `~/.claude/skills/<name>/SKILL.md`.
+ * `CLAUDE_CONFIG_DIR` is how somebody moves that directory, and honouring it is
+ * the difference between installing the skill and installing it somewhere
+ * nothing will ever read it.
+ */
+export const target = () =>
+  path.join(
+    process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'),
+    'skills',
+    'talea',
+    'SKILL.md',
+  );
+
+/**
+ * The marker that says a file at that path is ours.
+ *
+ * Somebody may already have their own skill called `talea`. Overwriting it
+ * would destroy work this tool has no claim on, so the only file `install`
+ * will replace is one carrying this line, and the only file `uninstall` will
+ * delete is the same.
+ */
+const MARK = '<!-- talea-skill:';
+
+export const isOurs = (file) => {
+  try {
+    return readFileSync(file, 'utf8').includes(MARK);
+  } catch {
+    return false;
+  }
+};
+
+export const help = `
+${c.bold('talea skill')} — teach your coding agent to drive talea
+
+  ${c.dim('talea skill')}             is it installed, and where
+  ${c.dim('talea skill install')}     copy it into ~/.claude/skills/talea/
+  ${c.dim('talea skill uninstall')}   take it back out
+
+Installs at ${c.bold('user scope')}, so every project you open gets it — your workspace
+spans all of them, and the agent needs the same instructions in each.
+
+The skill is what turns ${c.dim('"where is eklavya?"')} and ${c.dim('"tidy up my repos"')} into the
+right talea command, with the guardrails attached: an adopt is always dry-run
+first, ${c.dim('--loose')} is never taken on your behalf, and nothing is ever deleted.
+
+It refuses to overwrite a skill called ${c.dim('talea')} that this tool did not write.
+Move yours first if you have one.
+`;
+
+export function run(opts, positionals = []) {
+  const action = positionals[0] ?? 'status';
+  const dest = target();
+
+  if (action === 'status') return status(dest);
+  if (action === 'install') return install(dest);
+  if (action === 'uninstall' || action === 'remove') return uninstall(dest);
+
+  fail(`Unknown: talea skill ${action}`);
+  plain(`\n  Try ${c.dim('talea skill install')}, ${c.dim('talea skill uninstall')}, or ${c.dim('talea skill')} on its own.`);
+  // `process.exitCode`, not `process.exit()` — the same contract `summary()`
+  // uses, and the only one a test can drive without taking the runner down.
+  process.exitCode = 1;
+}
+
+function status(dest) {
+  heading('talea skill');
+  if (!existsSync(dest)) {
+    warn('Not installed.');
+    plain(`\n  ${c.dim('talea skill install')}   put it in ${c.bold(dest)}`);
+    return;
+  }
+  if (!isOurs(dest)) {
+    warn(`Something else owns ${c.bold(dest)}.`);
+    plain(`\n  It is not a file talea wrote, so talea will not touch it.`);
+    return;
+  }
+  const same = readFileSync(dest, 'utf8') === readFileSync(source, 'utf8');
+  ok(`Installed at ${c.bold(dest)}`);
+  if (!same) {
+    plain(`\n  ${c.yellow('Out of date')} — ${c.dim('talea skill install')} rewrites it from this version.`);
+  }
+}
+
+function install(dest) {
+  heading('talea skill install');
+
+  if (existsSync(dest) && !isOurs(dest)) {
+    // Somebody's own skill, under the name we want. Never overwrite it: it is
+    // work this tool has no claim on, and there is no undo.
+    fail(`There is already a skill called "talea" at ${c.bold(dest)}, and talea did not write it.`);
+    plain(`\n  Move it somewhere else first, then run this again. Nothing has been changed.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  mkdirSync(path.dirname(dest), { recursive: true });
+  copyFileSync(source, dest);
+  ok(`Installed ${c.bold(dest)}`);
+  info(`Restart Claude Code to pick it up — skills are read at session start.`);
+  plain(`\n  Then ${c.dim('"where is eklavya?"')} or ${c.dim('"sync my repos"')} reaches the right command on its own.`);
+}
+
+function uninstall(dest) {
+  heading('talea skill uninstall');
+
+  if (!existsSync(dest)) {
+    info('Nothing to remove.');
+    return;
+  }
+  if (!isOurs(dest)) {
+    fail(`${c.bold(dest)} is not a file talea wrote — leaving it alone.`);
+    process.exitCode = 1;
+    return;
+  }
+  rmSync(dest, { force: true });
+  // The directory is ours too, and an empty one left behind shows up in
+  // `/skills` as a skill with no file.
+  rmSync(path.dirname(dest), { recursive: true, force: true });
+  ok(`Removed ${c.bold(dest)}`);
+}

package/src/theme.js

@@ -24,18 +24,23 @@ export const useColor =
 // fallback and uses it whenever COLORTERM is not set.
 const trueColor = /^(truecolor|24bit)$/i.test(process.env.COLORTERM ?? '');
 
-// ── Phosphor palette ───────────────────────────────────────────
-// [24-bit hex, basic-16 SGR code]. The basic code is what a terminal without
-// COLORTERM gets; it is deliberately the closest *readable* match rather than
-// the closest numerically — `faint` has no bright equivalent, so it falls back
-// to grey rather than a green nobody can read on a light background.
+// ── Verdigris palette ──────────────────────────────────────────
+// [24-bit hex, basic-16 SGR code]. The same accent ramp the website is built
+// on — verdigris, new growth on aged bronze — so the CLI and talea.run are one
+// product rather than two that share a name. The hexes are the `--vd-*` steps in
+// `web/public/tokens.css`; change one and change the other.
+//
+// The basic code is what a terminal without COLORTERM gets. It is deliberately
+// the closest *readable* match rather than the closest numerically — `faint`
+// has no bright equivalent, so it falls back to grey rather than a teal nobody
+// can read on a light background.
 const PALETTE = {
-  green: ['#39ff14', 92], // hot phosphor — something worked
-  aged: ['#1f8a3b', 32], // settled green — a branch, a path, a detail
-  faint: ['#0e3b1c', 90], // barely lit — rules and fills
-  amber: ['#ffb000', 33], // attention, but not a failure
-  red: ['#ff3b30', 31], // failure
-  bone: ['#d6dbd6', 37], // plain text that still wants to be lit
+  green: ['#79D5C4', 96], // --vd-300, the accent — something worked
+  aged: ['#199688', 36], // --vd-500 — a branch, a path, a detail
+  faint: ['#07403C', 90], // --vd-800 — rules and fills
+  amber: ['#E8920C', 33], // --warning: attention, but not a failure
+  red: ['#E5484D', 31], // --error: failure
+  bone: ['#EAE7E1', 37], // --ink: plain text that still wants to be lit
 };