@openagt/skill-branches 0.1.3 → 0.1.5

package/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: branches
+description: Where your work goes (a branch named agent-<name>), how to name it, what must be true before you finish, and how to push it when you are asked to.
+package: "@openagt/skill-branches@0.1"
+---
+
+# Branch management
+
+Your work goes on a branch named `agent-<name>`, unless whoever started you continued you on another. It stays on this machine until you are asked to push it.
+
+## The command
+
+Run the `branches` command inside your checkout, always by its full name: `npx @openagt/skill-branches@0.1`. `status`, `name` and `push` (with no flag) are yours; the rest are the caller's.
+
+## Where you are
+
+```
+npx @openagt/skill-branches@0.1 status
+```
+
+It prints JSON; `branch` is the branch you are on.
+
+**A branch starting with `agent-`.** Its checkout is your whole workspace: read and write only there. Dependency files and skill folders are links to the user's copies: never edit them. If something you need is outside your checkout, say so and stop.
+
+Before your first change, name the session with `[a-z0-9-]+`, starting with a letter or digit, saying what the work is, unless your branch already differs from `path`'s last segment: then it is named, keep it.
+
+```
+npx @openagt/skill-branches@0.1 name <name>
+```
+
+It renames your branch to `agent-<name>` and prints it in `branch`: `agent-<name>-2`, `-3`, … when `<name>` was taken; a name outside `[a-z0-9-]+` is refused as `invalid-name`.
+
+**Any other branch.** If the checkout sits under `.branches/`, you were put on this branch on purpose: stay on it, do not name it. Otherwise you are in a plain clone on someone else's branch. Before your first change, create your own and switch to it, `<name>` as above (another if it exists, locally or on origin):
+
+```
+git switch -c agent-<name>
+```
+
+From then on, work as on an `agent-` branch; nothing in a plain clone is a link.
+
+## Commit as you go
+
+Nothing is committed for you.
+
+## Before you finish
+
+```
+npx @openagt/skill-branches@0.1 status
+```
+
+It must report `"clean": true`. `clean` is false while anything is uncommitted or untracked: commit or delete what you added; if what remains is not yours, say so and finish.
+
+## Push
+
+Only when your task or the person asks you to push or publish your work, and once clean:
+
+```
+npx @openagt/skill-branches@0.1 push
+```
+
+It pushes your branch to origin and prints it in `branch`. `clean` false is refused as `dirty`: commit or delete first.
+
+## Merge
+
+Only when the person asks you to merge your work into the project's main branch, and once clean:
+
+```
+npx @openagt/skill-branches@0.1 merge <your branch>
+```
+
+It merges your branch into the main branch, in the project's own folder. A conflict changes nothing and names the files in `files`: say so and stop. Your checkout and your branch stay.

package/dist/command-link.d.ts

@@ -14,8 +14,8 @@ import { type GitRunner } from '@openagt/agent-data';
  * The package is linked only beside its own commands. Beside another tool that holds a command's
  * name in the project, the full name would run that tool, so there it is left to npm.
  *
- * Hidden from the project's git through the repository's exclude file, like a skill's link: a link
- * is the package's state, not the agent's work. Best-effort: an entry already there (the project's
+ * Hidden from the project's git through the repository's exclude file: a link is the package's
+ * state, not the agent's work, and `node_modules` is never a person's. Best-effort: an entry already there (the project's
  * own copy) is left alone, a link of this package's that points nowhere is made again, and a link
  * that cannot be made is a worse run, not a failed one.
  */

package/dist/skill-links.d.ts

@@ -37,11 +37,11 @@ export interface SkillLink {
 export declare const OWN_SKILL: SkillLink;
 /**
  * Link the skill into `checkout` for every harness — this package's own, plus whatever `skills`
- * the caller names (see {@link SkillLink}) — and hide the links from the project's git
- * through the repository's exclude file: a symlink at the checkout root would otherwise ride any
- * sweeping `git add -A` onto the agent's branch. Best-effort: an entry already at a link's path is
- * left alone and gets no rule, a link of this package's that points nowhere is made again, and a
- * link that cannot be made is a worse run, not a failed one.
+ * the caller names (see {@link SkillLink}) — and hide the links from the project's git (see
+ * {@link hideLink}): a symlink at the checkout root would otherwise ride any sweeping `git add -A`
+ * onto the agent's branch. Best-effort: an entry already at a link's path is left alone and is not
+ * hidden, a link of this package's that points nowhere is made again, and a link that cannot be
+ * made is a worse run, not a failed one.
  */
 export declare function linkSkill(repo: string, checkout: string, fs?: LinkFs, git?: GitRunner, skills?: readonly SkillLink[]): Promise<void>;
 /** The paths of a skill's links, relative to a checkout: its text for every harness, and its package's links when it has one. */

package/dist/skill-links.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-links.d.ts","sourceRoot":"","sources":["../src/skill-links.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,SAAS,EAAkB,MAAM,qBAAqB,CAAA;AACnF,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAA8C,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEhG;;;;;;;;GAQG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,UAAU,aAAa,CAAA;AAEpC,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,YAAI,gBAAgB,EAAE,gBAAgB,CAAU,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,SAAS,QAAsD,CAAA;AAE5E;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,uIAAuI;IACvI,OAAO,CAAC,EAAE,WAAW,CAAA;CACtB;AAED,wDAAwD;AACxD,eAAO,MAAM,SAAS,EAAE,SAAgD,CAAA;AAExE;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,EAAE,GAAE,MAAqB,EACzB,GAAG,GAAE,SAA2B,EAChC,MAAM,GAAE,SAAS,SAAS,EAAO,GAChC,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED,iIAAiI;AACjI,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAEzD"}
+{"version":3,"file":"skill-links.d.ts","sourceRoot":"","sources":["../src/skill-links.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,SAAS,EAAkB,MAAM,qBAAqB,CAAA;AACnF,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAA8C,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEhG;;;;;;;;GAQG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,UAAU,aAAa,CAAA;AAEpC,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,YAAI,gBAAgB,EAAE,gBAAgB,CAAU,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,SAAS,QAAsD,CAAA;AAE5E;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,uIAAuI;IACvI,OAAO,CAAC,EAAE,WAAW,CAAA;CACtB;AAED,wDAAwD;AACxD,eAAO,MAAM,SAAS,EAAE,SAAgD,CAAA;AAExE;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,EAAE,GAAE,MAAqB,EACzB,GAAG,GAAE,SAA2B,EAChC,MAAM,GAAE,SAAS,SAAS,EAAO,GAChC,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED,iIAAiI;AACjI,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAEzD"}

package/dist/skill-links.js

@@ -1,3 +1,4 @@
+import { readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { nodeGitRunner, excludeFromGit } from '@openagt/agent-data';
@@ -25,11 +26,11 @@ export const SKILL_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
 export const OWN_SKILL = { name: SKILL_NAME, dir: SKILL_DIR };
 /**
  * Link the skill into `checkout` for every harness — this package's own, plus whatever `skills`
- * the caller names (see {@link SkillLink}) — and hide the links from the project's git
- * through the repository's exclude file: a symlink at the checkout root would otherwise ride any
- * sweeping `git add -A` onto the agent's branch. Best-effort: an entry already at a link's path is
- * left alone and gets no rule, a link of this package's that points nowhere is made again, and a
- * link that cannot be made is a worse run, not a failed one.
+ * the caller names (see {@link SkillLink}) — and hide the links from the project's git (see
+ * {@link hideLink}): a symlink at the checkout root would otherwise ride any sweeping `git add -A`
+ * onto the agent's branch. Best-effort: an entry already at a link's path is left alone and is not
+ * hidden, a link of this package's that points nowhere is made again, and a link that cannot be
+ * made is a worse run, not a failed one.
  */
 export async function linkSkill(repo, checkout, fs = nodeLinkFs(), git = nodeGitRunner(), skills = []) {
     for (const skill of [OWN_SKILL, ...skills]) {
@@ -37,11 +38,11 @@ export async function linkSkill(repo, checkout, fs = nodeLinkFs(), git = nodeGit
             const rel = `${dir}/${skill.name}`;
             try {
                 const path = join(checkout, rel);
-                // The project's own copy, tracked or not, stays, and gets no rule: a rule would hide what a person adds there.
+                // The project's own copy, tracked or not, stays, and is not hidden: that would hide what a person adds there.
                 if (await entryExists(path))
                     continue;
-                await excludeFromGit(repo, `/${rel}`, undefined, git).catch(() => { });
                 await fs.mkdir(join(checkout, dir));
+                await hideLink(repo, checkout, dir, skill.name, git).catch(() => { });
                 await fs.symlinkDir(skill.dir, path);
             }
             catch {
@@ -56,4 +57,24 @@ export async function linkSkill(repo, checkout, fs = nodeLinkFs(), git = nodeGit
 export function skillLinkPaths(skill) {
     return [...HARNESS_SKILL_DIRS.map(dir => `${dir}/${skill.name}`), ...(skill.package ? packageLinkPaths(skill.package) : [])];
 }
+/** The file a skill's link is hidden by, in the folder the link is in. */
+const IGNORE_FILE = '.gitignore';
+/**
+ * Hide the link `<dir>/<name>` by a line in `<dir>/.gitignore` of the agent's checkout, a file that
+ * names itself too, so it is hidden as well. The file is in that checkout only: a person who adds a
+ * skill of the same name in their own checkout sees it in git, where a rule in the repository's
+ * exclude file, read by every checkout of it, hid it from them too. A project that tracks its own
+ * `<dir>/.gitignore` gets no line in it, which would be work for the agent to commit: there the
+ * link is hidden by the repository's exclude file.
+ */
+async function hideLink(repo, checkout, dir, name, git) {
+    const tracked = (await git(['ls-files', '--', `${dir}/${IGNORE_FILE}`], checkout)).trim() !== '';
+    if (tracked)
+        return excludeFromGit(repo, `/${dir}/${name}`, undefined, git);
+    const file = join(checkout, dir, IGNORE_FILE);
+    const current = await readFile(file, 'utf8').catch(() => `/${IGNORE_FILE}\n`);
+    if (current.split('\n').includes(`/${name}`))
+        return;
+    await writeFile(file, (current.endsWith('\n') ? current : `${current}\n`) + `/${name}\n`);
+}
 //# sourceMappingURL=skill-links.js.map

package/dist/skill-links.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-links.js","sourceRoot":"","sources":["../src/skill-links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,aAAa,EAAkB,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACnF,OAAO,EAAE,UAAU,EAAe,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAoB,MAAM,mBAAmB,CAAA;AAEhG;;;;;;;;GAQG;AAEH,6GAA6G;AAC7G,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAA;AAEpC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAU,CAAA;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AAiB5E,wDAAwD;AACxD,MAAM,CAAC,MAAM,SAAS,GAAc,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,CAAA;AAExE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAY,EACZ,QAAgB,EAChB,EAAE,GAAW,UAAU,EAAE,EACzB,GAAG,GAAc,aAAa,EAAE,EAChC,MAAM,GAAyB,EAAE;IAEjC,KAAK,MAAM,KAAK,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;YACrC,MAAM,GAAG,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAA;YAClC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;gBAChC,+GAA+G;gBAC/G,IAAI,MAAM,WAAW,CAAC,IAAI,CAAC;oBAAE,SAAQ;gBACrC,MAAM,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;gBACrE,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAA;gBACnC,MAAM,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,iFAAiF;YACnF,CAAC;QACH,CAAC;QACD,IAAI,KAAK,CAAC,OAAO;YAAE,MAAM,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;IAC1E,CAAC;AACH,CAAC;AAED,iIAAiI;AACjI,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,OAAO,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAC9H,CAAC"}
+{"version":3,"file":"skill-links.js","sourceRoot":"","sources":["../src/skill-links.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagt/skill-branches",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Branch management for coding agents: one git checkout per agent under .branches/, named as its branch, reclaimed once its work is on the remote.",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
     }
   },
   "dependencies": {
-    "@openagt/agent-data": "0.0.8"
+    "@openagt/agent-data": "0.0.9"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",