gcf-aif-ext 0.26.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,6 +50,13 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
50
50
 
51
51
  On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
52
52
 
53
+ ### 0.27.0
54
+
55
+ - **`gcf changes push` and `gcf changes pull`** ([Push-Plan](https://github.com/VirtualMaestro/GCF/blob/main/docs/Push-Plan.md)): the board's Push and Pull. Push sends the main checkout's branch to its upstream, fast-forward only: no `+`, no `--force`, no `--no-verify`, and no flag that adds one. With no upstream it pushes to `origin`, or the only remote, with `-u`; `--remote <name>` picks another. Pull is `fetch` and `merge --ff-only` of the same target: a branch with commits of its own over the remote's is refused as `diverged`, main untouched, and the merge is the agent's (`git pull --no-rebase`). Pull claims the checkout as a build by click does: no run starts meanwhile.
56
+ - Both refuse on a `work/` branch, a detached HEAD, a merge or rebase in progress, and while a run writes in main (`running`). The other refusals end with `gcf-refusal`: `no-remote`, `no-upstream` with `remotes`, `behind`, `rejected` (a pre-push hook or the server), `auth`, `timeout`, `diverged`. git runs with no terminal prompt and stops after 90 s: on Windows the Git Credential Manager's sign-in window still opens.
57
+ - `gcf changes --json` of the main checkout has a `branch` block from local refs, no network: its upstream, how many commits are ahead and behind as of the last fetch, and the first 20 that a push sends with who made each (`GCF-By`, none is the operator). `sections.changes` has `push` and `pull`.
58
+ - The project chat asks before `changes push`, `changes pull`, `git push` and `git pull`.
59
+
53
60
  ### 0.24.0
54
61
 
55
62
  - A card's unfinished work in main mode goes to its branch when another card claims the folder (Methodology §7, [Shelve-Plan](https://github.com/VirtualMaestro/GCF/blob/main/docs/Shelve-Plan.md)). `gcf claim` pins a baseline at `refs/gcf/main-work`; the next card's claim moves what the card changed since to `work/<id>` as a commit with `GCF-Shelved: <id>`, untouched files keep their mtime, and no hook runs. Its own claim brings the work back by a three-way merge: conflicts stay as markers in the file, for the agent. A journal, `refs/gcf/main-switch`, makes every step recoverable.
@@ -338,7 +345,7 @@ The run layer of the methodology. Update both extensions together — `gcf-harne
338
345
  - `gcf phase` and `gcf phase next [--reason]` — the project phase (prototype → vertical-slice → alpha → beta → release → live), kept as `phase:` in the `LIVE.md` frontmatter, with exit criteria checked in code. `item new` and `take` refuse a type the phase does not take. **A project with no phase yet is in prototype, and a prototype takes no `asset` item**: move the phase on (`gcf phase next --reason "…"`) if your game is past it. A `phases:` list in `config.yml` replaces the set.
339
346
  - A release item carries `version:` and `channel:` (`item new <id> --type release --release 1.0.0 --channel steam`); its end writes the `release:` block of `LIVE.md`. `item new --milestone <name>` tags an item with a milestone of `game.md` (any slug without `game.md`); `design check` reports (does not block) an item whose milestone `game.md` does not list, and the board read gives the list as `design.milestones`.
340
347
  - `gcf playtest session` — where main stands and a checklist per item: its build, what to check, how to get there, what to feel.
341
- - `gcf playtest build <id> [--from <worktree>] [--fresh]`, `build --main [--fresh]`, `start <id>|--main --target <name>`, `stop`, `status`, `setup` — one build per code under `.gcf-session/snaps/<key>/`, held by a card's link `.gcf-session/builds/<id>.json` or the checkout's `snaps/main.link.json`, and its player, from `play:` in `gcf/config.yml`; a verdict stops the card's player and removes the build once no other card holds it. `setup` refuses an output git does not ignore. The deny group `run-play` keeps a run's agent from building; a chat thread may build on the human's ask.
348
+ - `gcf playtest build <id> [--from <worktree>] [--fresh]`, `build --main [--fresh]`, `start <id>|--main --target <name>`, `stop`, `status`, `setup` — one build per code under `.gcf-session/snaps/<key>/`, held by a card's link `.gcf-session/builds/<id>.json` or the checkout's `snaps/main.link.json`, and its player, from `play:` in `gcf/config.yml`; a verdict stops the card's player and removes the build once no other card holds it. `setup` refuses an output git does not ignore. On Windows the project's commands (`play:`, `dod.*`) run with Git's `bin` first in PATH, so `bash` is Git's, not System32's WSL launcher. The deny group `run-play` keeps a run's agent from building; a chat thread may build on the human's ask.
342
349
  - `gcf worktree <id>`, `gcf verify <id> --mark`, `gcf integrate [<id>…]` — an item in its own worktree, the `GCF-Verified` trailer, the merge into main and the item's move. Every committed move now holds `.gcf-session/main.lock`.
343
350
  - `gcf board [--json]` — everything a board shows in one read.
344
351
 
@@ -407,6 +414,7 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
407
414
  - design and sources — `design check`, `design export`, `design import`, `design part`, `design save`, `design discard`, `design commit`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
408
415
  - hand edits under `gcf/` — `edits diff|commit|discard --path <p>…`: what a move's `dirty` refusal names, shown, committed or put back
409
416
  - what is uncommitted, anywhere in the project — `changes [--worktree <id>] [--json]`, `changes diff --path <p>`, `changes file --path <p> --side base|now`: read only; the project's `no_diff:` globs, links, submodules, nested repositories and Git LFS files are listed and never opened
417
+ - the main checkout's branch and its remote — `changes push|pull [--remote <name>] [--json]`: fast-forward only, never a force
410
418
  - setup — `init`, `index`, `hooks-install`
411
419
 
412
420
  Every move of an item makes one commit `gcf(<move>): <id>` with every file it touched — the item, history or graveyard, `LIVE.md`, the systems documents, the parent feature, a removal item, the archived plan. `take`, `item new` and `inbox` do not commit. These are plain Node scripts with no LLM in the loop: the same functions the skills call, the pre-commit gate runs, and the harness gates against.
package/commands/gcf.js CHANGED
@@ -1018,6 +1018,51 @@ function registerChangesCommit(group, allOf) {
1018
1018
  ).commitFiles(process.cwd(), fieldsOf(o.fieldsFile));
1019
1019
  out(o.json, r, (x) => `committed ${x.files} file${x.files === 1 ? '' : 's'} ${x.hash}`);
1020
1020
  });
1021
+ registerChangesPush(group, allOf);
1022
+ }
1023
+
1024
+ const plural = (n) => `${n} commit${n === 1 ? '' : 's'}`;
1025
+
1026
+ // Push and a fast-forward Pull of the main checkout's branch (docs/Push-Plan.md): never a force.
1027
+ function registerChangesPush(group, allOf) {
1028
+ const REMOTE = 'the remote to use when the branch has no upstream, or another than its own';
1029
+ const noTree = (o, move) => {
1030
+ if (o.worktree)
1031
+ throw new Error(`changes ${move}: main only; a run's work reaches it by integrate`);
1032
+ };
1033
+
1034
+ group
1035
+ .command('push')
1036
+ .description("Push the main checkout's branch to its upstream, fast-forward only, never force")
1037
+ .option('--remote <name>', REMOTE)
1038
+ .option('--json', '{remote, branch, upstream, from, to, pushed, set_upstream}')
1039
+ .action(async (own, cmd) => {
1040
+ const o = allOf(own, cmd);
1041
+ noTree(o, 'push');
1042
+ const r = await (await lib('push')).pushBranch(process.cwd(), { remote: o.remote });
1043
+ out(o.json, r, (x) =>
1044
+ x.pushed
1045
+ ? `pushed ${plural(x.pushed)} to ${x.upstream} ${x.from ?? 'new'}..${x.to}`
1046
+ : `${x.upstream} is up to date`,
1047
+ );
1048
+ });
1049
+ group
1050
+ .command('pull')
1051
+ .description(
1052
+ "Bring the push target's new commits in, fast-forward only: a merge is the agent's",
1053
+ )
1054
+ .option('--remote <name>', REMOTE)
1055
+ .option('--json', '{remote, branch, upstream, from, to, pulled}')
1056
+ .action(async (own, cmd) => {
1057
+ const o = allOf(own, cmd);
1058
+ noTree(o, 'pull');
1059
+ const r = await (await lib('push')).pullBranch(process.cwd(), { remote: o.remote });
1060
+ out(o.json, r, (x) =>
1061
+ x.pulled
1062
+ ? `pulled ${plural(x.pulled)} from ${x.upstream} ${x.from}..${x.to}`
1063
+ : 'nothing to pull',
1064
+ );
1065
+ });
1021
1066
  }
1022
1067
 
1023
1068
  function registerMigrate(design) {
package/extension.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
3
3
  "name": "gcf-aif-ext",
4
- "version": "0.26.0",
4
+ "version": "0.27.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
package/lib/changes.js CHANGED
@@ -7,6 +7,7 @@ import { DIFF_FORM } from './edits.js';
7
7
  import { gcfRoot, readConfig } from './gcf-paths.js';
8
8
  import { isValidId } from './id.js';
9
9
  import { verifiedBranches, worktreeOf } from './integrate.js';
10
+ import { branchState } from './push.js';
10
11
  import { refusal } from './refusal.js';
11
12
  import { fileState, newFileDiff, readHead } from './tree-file.js';
12
13
 
@@ -499,7 +500,16 @@ export async function changesOf(projectDir, { worktree } = {}) {
499
500
  const { tree, rows, noDiff } = await readTree(projectDir, worktree);
500
501
  const name = worktree ?? 'main';
501
502
  if (!rows)
502
- return { tree: name, base: null, count: 0, files: [], trees: tree.trees, more: 0, watch: null };
503
+ return {
504
+ tree: name,
505
+ base: null,
506
+ count: 0,
507
+ files: [],
508
+ trees: tree.trees,
509
+ more: 0,
510
+ watch: null,
511
+ branch: null,
512
+ };
503
513
  const shown = rows.slice(0, LIST_MAX);
504
514
  const gitPath = (p) => line(tree.dir, 'rev-parse', '--git-path', p);
505
515
 
@@ -511,6 +521,8 @@ export async function changesOf(projectDir, { worktree } = {}) {
511
521
  trees: tree.trees,
512
522
  more: rows.length - shown.length,
513
523
  watch: { index: gitPath('index'), head: gitPath('HEAD') },
524
+ // What Push would send (docs/Push-Plan.md p4): the main checkout's branch only.
525
+ branch: worktree && worktree !== 'main' ? null : branchState(tree.dir),
514
526
  };
515
527
  }
516
528
 
package/lib/domain.js CHANGED
@@ -926,7 +926,8 @@ const SECTIONS = {
926
926
  edits: { commit: 'edits-commit', discard: 'edits-discard' },
927
927
  // `gcf changes` reads what is uncommitted: the board's Changes screen and its header's marker.
928
928
  // `commit`: its `gcf changes commit` takes the operator's ticked files and message.
929
- changes: { commit: true },
929
+ // `push`, `pull`: `gcf changes push|pull`, fast-forward only (docs/Push-Plan.md).
930
+ changes: { commit: true, push: true, pull: true },
930
931
  lessons: {},
931
932
  playtest: {
932
933
  // The inbox category a note from the playtest screen goes with.
@@ -973,6 +974,8 @@ const CHANGES = [
973
974
  'edits commit',
974
975
  'edits discard',
975
976
  'changes commit',
977
+ 'changes push',
978
+ 'changes pull',
976
979
  'take',
977
980
  'done',
978
981
  'drop',
@@ -1018,6 +1021,12 @@ const CHAT = {
1018
1021
  { kind: 'shell', pattern: 'ai-factory gcf context*--readset*' },
1019
1022
  // `verify` reads, but with `--mark` it commits a branch's readiness to merge.
1020
1023
  { kind: 'shell', pattern: 'ai-factory gcf verify*--mark*' },
1024
+ // What leaves the machine, or changes the checkout from outside: a click of the operator's.
1025
+ // A chain (`cd x && git push`) is matched per command by the engine; `git -C x push` is not.
1026
+ { kind: 'shell', pattern: 'git push*' },
1027
+ { kind: 'shell', pattern: 'git pull*' },
1028
+ { kind: 'shell', pattern: 'git -C * push*' },
1029
+ { kind: 'shell', pattern: 'git -C * pull*' },
1021
1030
  ],
1022
1031
  };
1023
1032
 
package/lib/play.js CHANGED
@@ -20,6 +20,7 @@ import { buildLedger } from './ledger.js';
20
20
  import { alive, claimMainRun, MAIN_RUN, runHolder, withMainLock } from './main-lock.js';
21
21
  import { atomicWrite, renameRetrying } from './safe-path.js';
22
22
  import { commitMove } from './unit-ops.js';
23
+ import { commandEnv } from './shell-env.js';
23
24
  import { failureOf, killTree, runCommand } from './verify.js';
24
25
 
25
26
  export const NOT_SET_UP =
@@ -683,6 +684,7 @@ const runStop = (dir, command) =>
683
684
  spawnSync(command, {
684
685
  cwd: dir,
685
686
  shell: true,
687
+ env: commandEnv(),
686
688
  stdio: 'ignore',
687
689
  timeout: STOP_WAIT_MS,
688
690
  windowsHide: true,
@@ -771,6 +773,8 @@ function launch(dir, command) {
771
773
  const child = spawn(process.execPath, ['-e', KEEPER, command], {
772
774
  cwd: dir,
773
775
  detached: true,
776
+ // The keeper's shell takes it: the start finds the `bash` its agent tried.
777
+ env: commandEnv(),
774
778
  stdio: ['ignore', log, log],
775
779
  windowsHide: true,
776
780
  });
@@ -980,9 +984,8 @@ export async function playStatus(projectDir) {
980
984
  * @param {{build?: string, output?: string, target?: string, start?: string, open?: string,
981
985
  * stop?: string, removeTarget?: string, commit?: boolean}} opts
982
986
  */
983
- export async function setupPlay(projectDir, opts) {
984
- const dir = path.resolve(projectDir);
985
- const { build, output, target, start, open: words, stop, removeTarget, commit = true } = opts;
987
+ /** What a setup may not be: checked before anything is written. */
988
+ function needSetup(dir, { output, target, start, words, stop }) {
986
989
  if (target !== undefined && !/^\w[\w-]*$/.test(target))
987
990
  throw new Error(`a target's name is one word: ${target}`);
988
991
  if (target === undefined && [start, words, stop].some((v) => v !== undefined))
@@ -991,32 +994,54 @@ export async function setupPlay(projectDir, opts) {
991
994
  if (output !== undefined) needOutput(output);
992
995
  if (output !== undefined && !ignored(dir, output))
993
996
  throw new Error(`play.output ${output} is not ignored by git: add it to .gitignore`);
994
- const file = path.join(dir, 'gcf', 'config.yml');
995
- const hash = await commitMove(dir, 'gcf(config): play', {
996
- files: [file],
997
- commit,
998
- key: 'config',
999
- mutate: async () => {
1000
- const doc = configDoc(existsSync(file) ? readFileSync(file, 'utf8') : '');
1001
- const set = (keys, v) => v !== undefined && doc.setIn(['play', ...keys], v);
1002
- if (!YAML.isMap(doc.getIn(['play'], true))) doc.setIn(['play'], doc.createNode({}));
1003
- set(['build'], build);
1004
- set(['output'], output);
1005
- if (target !== undefined) {
1006
- if (!YAML.isMap(doc.getIn(['play', 'targets'], true)))
1007
- doc.setIn(['play', 'targets'], doc.createNode({}));
1008
- if (!YAML.isMap(doc.getIn(['play', 'targets', target], true)))
1009
- doc.setIn(['play', 'targets', target], doc.createNode({}));
1010
- set(['targets', target, 'start'], start);
1011
- set(['targets', target, 'open'], words);
1012
- set(['targets', target, 'stop'], stop);
1013
- }
997
+ }
1014
998
 
1015
- if (removeTarget !== undefined) doc.deleteIn(['play', 'targets', removeTarget]);
1016
- playOf(doc.toJS());
1017
- await atomicWrite(file, doc.toString());
1018
- },
1019
- });
999
+ /** config.yml's text with `play:` changed as given; what is not given stays. */
1000
+ function playDoc(text, { build, output, target, start, words, stop, removeTarget }) {
1001
+ const doc = configDoc(text);
1002
+ const set = (keys, v) => v !== undefined && doc.setIn(['play', ...keys], v);
1003
+ if (!YAML.isMap(doc.getIn(['play'], true))) doc.setIn(['play'], doc.createNode({}));
1004
+ set(['build'], build);
1005
+ set(['output'], output);
1006
+ if (target !== undefined) {
1007
+ if (!YAML.isMap(doc.getIn(['play', 'targets'], true)))
1008
+ doc.setIn(['play', 'targets'], doc.createNode({}));
1009
+ if (!YAML.isMap(doc.getIn(['play', 'targets', target], true)))
1010
+ doc.setIn(['play', 'targets', target], doc.createNode({}));
1011
+ set(['targets', target, 'start'], start);
1012
+ set(['targets', target, 'open'], words);
1013
+ set(['targets', target, 'stop'], stop);
1014
+ }
1015
+
1016
+ if (removeTarget !== undefined) doc.deleteIn(['play', 'targets', removeTarget]);
1017
+
1018
+ return doc;
1019
+ }
1020
+
1021
+ export async function setupPlay(projectDir, opts) {
1022
+ const dir = path.resolve(projectDir);
1023
+ const { build, output, target, start, open: words, stop, removeTarget, commit = true } = opts;
1024
+ needSetup(dir, { output, target, start, words, stop });
1025
+ const file = path.join(dir, 'gcf', 'config.yml');
1026
+ const was = existsSync(file) ? readFileSync(file, 'utf8') : '';
1027
+ const doc = playDoc(was, { build, output, target, start, words, stop, removeTarget });
1028
+ // The same setup again (an agent proposed what is there): nothing to write, nothing to commit.
1029
+ const same =
1030
+ JSON.stringify(configDoc(was).toJS()?.play ?? null) === JSON.stringify(doc.toJS().play);
1031
+ const hash = same
1032
+ ? null
1033
+ : await commitMove(dir, 'gcf(config): play', {
1034
+ files: [file],
1035
+ commit,
1036
+ key: 'config',
1037
+ mutate: async () => {
1038
+ // Read again under the lock: a move meanwhile may have changed the file.
1039
+ const now = existsSync(file) ? readFileSync(file, 'utf8') : '';
1040
+ const next = playDoc(now, { build, output, target, start, words, stop, removeTarget });
1041
+ playOf(next.toJS());
1042
+ await atomicWrite(file, next.toString());
1043
+ },
1044
+ });
1020
1045
 
1021
1046
  return { hash, play: playOf(await readConfig(path.join(dir, 'gcf'))) };
1022
1047
  }
package/lib/push.js ADDED
@@ -0,0 +1,384 @@
1
+ // Push and a safe Pull of the main checkout's branch (docs/Push-Plan.md, Board-PRD decision 56):
2
+ // the board's Push button and `gcf changes push|pull`. Never a force: what left the machine comes
3
+ // back only by rewriting history others may hold. Pull only fast-forwards; a merge is the agent's.
4
+ import { spawn, spawnSync } from 'node:child_process';
5
+ import { operationInProgress } from './git.js';
6
+ import { claimMainRun, MAIN_RUN, runHolder, withMainLock } from './main-lock.js';
7
+ import { refusal } from './refusal.js';
8
+ import { onWorkBranch } from './unit-ops.js';
9
+ import { killTree } from './verify.js';
10
+
11
+ export const NET_TIMEOUT_MS = 90_000;
12
+ const OUT_MAX = 20;
13
+ const BY = ['run', 'thread', 'session', 'operator'];
14
+ const FS = '\x1f';
15
+ const RS = '\x1e';
16
+
17
+ const git = (dir, args, opts = {}) =>
18
+ spawnSync('git', ['-c', 'core.quotePath=false', ...args], {
19
+ cwd: dir,
20
+ encoding: 'utf8',
21
+ ...opts,
22
+ });
23
+
24
+ const line = (dir, ...args) => {
25
+ const r = git(dir, args);
26
+
27
+ return r.status === 0 ? r.stdout.trim() : null;
28
+ };
29
+
30
+ /**
31
+ * git over the network, stopped with its whole tree past `ms`: a sign-in helper (Git Credential
32
+ * Manager's window, `git-remote-https`) is git's child and would outlive a kill of git alone.
33
+ * `exit`, not `close`: such a helper may hold the pipes open. No terminal to ask a password in:
34
+ * git fails instead of waiting; the sign-in window stays, on Windows it is the operator's way in.
35
+ * shortcut: ssh passphrase prompt is only bounded by the timeout; add -o BatchMode=yes if it bites
36
+ */
37
+ function netGit(dir, args, ms) {
38
+ return new Promise((resolve) => {
39
+ const child = spawn('git', args, {
40
+ cwd: dir,
41
+ env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
42
+ stdio: ['ignore', 'pipe', 'pipe'],
43
+ windowsHide: true,
44
+ });
45
+ let stdout = '';
46
+ let stderr = '';
47
+ let timedOut = false;
48
+ child.stdout.on('data', (d) => (stdout += d));
49
+ child.stderr.on('data', (d) => (stderr += d));
50
+ const timer = setTimeout(() => {
51
+ timedOut = true;
52
+ killTree(child.pid);
53
+ }, ms);
54
+ child.on('error', (error) => {
55
+ clearTimeout(timer);
56
+ resolve({ status: null, stdout, stderr: `${stderr}${error.message}`, timedOut });
57
+ });
58
+ child.on('exit', (status) => {
59
+ clearTimeout(timer);
60
+ // What was written before the exit is still in the pipes: a tick to read it.
61
+ setImmediate(() => resolve({ status, stdout, stderr, timedOut }));
62
+ });
63
+ });
64
+ }
65
+
66
+ const remotesOf = (dir) => (line(dir, 'remote') ?? '').split('\n').filter(Boolean);
67
+
68
+ /**
69
+ * The branch's upstream: `up` is `{remote, ref, short, track}`, `track` git's own tracking ref;
70
+ * `local` for one on a local branch, which a push leaves alone. `born`: the branch has a commit.
71
+ */
72
+ function upstreamOf(dir, branch) {
73
+ const r = line(
74
+ dir,
75
+ 'for-each-ref',
76
+ `--format=%(objectname)${FS}%(upstream:remotename)${FS}%(upstream:remoteref)${FS}` +
77
+ `%(upstream:short)${FS}%(upstream)`,
78
+ `refs/heads/${branch}`,
79
+ );
80
+ const [head, remote, ref, short, track] = (r ?? '').split(FS);
81
+ if (!head) return { born: false };
82
+ if (remote === '.') return { born: true, local: true };
83
+
84
+ return {
85
+ born: true,
86
+ up: remote && ref?.startsWith('refs/heads/') ? { remote, ref, short, track } : null,
87
+ };
88
+ }
89
+
90
+ /**
91
+ * Where Push sends the branch and Pull takes it from, one choice for both (p7, p9): `--remote`,
92
+ * else the upstream, else `origin` or the only remote with a branch of the same name.
93
+ * `set_upstream`: no upstream at all yet, a push sets it.
94
+ */
95
+ export function targetOf(dir, branch, asked, known = upstreamOf(dir, branch)) {
96
+ const remotes = remotesOf(dir);
97
+ if (asked && !remotes.includes(asked))
98
+ throw new Error(`no remote ${asked}: this repository has ${remotes.join(', ') || 'none'}`);
99
+ const { up, local } = known;
100
+ if (up && (!asked || asked === up.remote)) return { ...up, remotes, set_upstream: false };
101
+ if (!remotes.length)
102
+ throw refusal(
103
+ 'no-remote',
104
+ {},
105
+ 'no remote: add one from a terminal (git remote add origin <url>), then Push',
106
+ );
107
+ const remote = asked ?? defaultRemote(remotes);
108
+ if (!remote)
109
+ throw refusal(
110
+ 'no-upstream',
111
+ { remotes },
112
+ `${branch} has no upstream and there is no origin: name the remote ` +
113
+ `(ai-factory gcf changes push --remote <name>), one of ${remotes.join(', ')}`,
114
+ );
115
+
116
+ return {
117
+ remote,
118
+ ref: `refs/heads/${branch}`,
119
+ short: `${remote}/${branch}`,
120
+ track: `refs/remotes/${remote}/${branch}`,
121
+ remotes,
122
+ set_upstream: !up && !local,
123
+ };
124
+ }
125
+
126
+ /** `origin`, else the only remote, else none to choose. */
127
+ const defaultRemote = (remotes) =>
128
+ remotes.includes('origin') ? 'origin' : remotes.length === 1 ? remotes[0] : null;
129
+
130
+ const hashOf = (dir, ref) => line(dir, 'rev-parse', '-q', '--verify', `${ref}^{commit}`);
131
+
132
+ /** The commits of `range` a push sends, newest first, up to OUT_MAX: who made each by `GCF-By`. */
133
+ function outOf(dir, range) {
134
+ const r = git(dir, [
135
+ 'log',
136
+ `-n${OUT_MAX}`,
137
+ `--format=%h${FS}%s${FS}%(trailers:key=GCF-By,valueonly,separator=%x2C)${RS}`,
138
+ ...range,
139
+ '--',
140
+ ]);
141
+ if (r.status !== 0) return [];
142
+
143
+ return r.stdout
144
+ .split(RS)
145
+ .map((rec) => rec.replace(/^\n/, ''))
146
+ .filter(Boolean)
147
+ .map((rec) => {
148
+ const [hash, subject, by = ''] = rec.split(FS);
149
+ const named = by.trim().split(',').at(-1);
150
+
151
+ return { hash, subject, by: BY.includes(named) ? named : 'operator' };
152
+ });
153
+ }
154
+
155
+ const count = (dir, range) => Number(line(dir, 'rev-list', '--count', ...range, '--') ?? 0);
156
+
157
+ /** Behind and ahead of a tracking ref in one walk; null when the ref is not there. */
158
+ function aheadBehind(dir, track) {
159
+ const r = line(dir, 'rev-list', '--left-right', '--count', `${track}...HEAD`, '--');
160
+ if (!r) return null;
161
+ const [behind, ahead] = r.split(/\s+/).map(Number);
162
+
163
+ return { ahead, behind };
164
+ }
165
+
166
+ /**
167
+ * The main checkout's branch against its remote, from local refs only, no network (p4): `behind`
168
+ * is as of the last fetch. Null on a detached HEAD or a branch with no commit. Five git calls: a
169
+ * read of the marker every 30 s pays them.
170
+ * @param {string} dir
171
+ */
172
+ export function branchState(dir) {
173
+ const name = line(dir, 'symbolic-ref', '--short', '-q', 'HEAD');
174
+ if (!name) return null;
175
+ const known = upstreamOf(dir, name);
176
+ if (!known.born) return null;
177
+ const t = readTarget(dir, name, known);
178
+ if (!t) return { name, upstream: null, target: null, ...againstAll(dir) };
179
+ const counts = aheadBehind(dir, t.track);
180
+ const range = counts ? ['HEAD', `^${t.track}`] : ['HEAD', '--not', `--remotes=${t.remote}`];
181
+ const out = outOf(dir, range);
182
+ const ahead = counts ? counts.ahead : count(dir, range);
183
+
184
+ return {
185
+ name,
186
+ upstream: t.set_upstream || known.local ? null : t.short,
187
+ target: t.short,
188
+ remotes: t.remotes,
189
+ ahead,
190
+ behind: counts?.behind ?? 0,
191
+ out,
192
+ out_more: ahead - out.length,
193
+ };
194
+ }
195
+
196
+ /** The target a read shows: none with no remote, or none to choose. */
197
+ function readTarget(dir, name, known) {
198
+ try {
199
+ return targetOf(dir, name, undefined, known);
200
+ } catch {
201
+ return null;
202
+ }
203
+ }
204
+
205
+ /** No target: what no remote has yet, or nothing with no remote at all. */
206
+ function againstAll(dir) {
207
+ const remotes = remotesOf(dir);
208
+ const none = { remotes, ahead: 0, behind: 0, out: [], out_more: 0 };
209
+ if (!remotes.length) return none;
210
+ const range = ['HEAD', '--not', '--remotes'];
211
+ const out = outOf(dir, range);
212
+ const n = count(dir, range);
213
+
214
+ return { ...none, ahead: n, out, out_more: n - out.length };
215
+ }
216
+
217
+ /** Push and Pull go where Commit goes (p5), and never under a run in main (p7). */
218
+ function refuseWhereNoPush(dir, move) {
219
+ if (onWorkBranch(dir))
220
+ throw new Error(`cannot ${move} from a work/ branch: a run's work reaches main by integrate`);
221
+ const busy = operationInProgress(dir);
222
+ if (busy) throw new Error(`cannot ${move} while ${busy} is in progress`);
223
+ const branch = line(dir, 'symbolic-ref', '--short', '-q', 'HEAD');
224
+ if (!branch) throw new Error(`cannot ${move} on a detached HEAD: check out a branch first`);
225
+ if (!hashOf(dir, 'HEAD')) throw new Error(`cannot ${move}: ${branch} has no commit yet`);
226
+ if (runHolder(dir, MAIN_RUN))
227
+ throw refusal(
228
+ 'running',
229
+ {},
230
+ `cannot ${move} while a run writes in the main checkout: its commits are half a card`,
231
+ );
232
+
233
+ return branch;
234
+ }
235
+
236
+ /** The last lines git said, past its hints. */
237
+ const said = (r) =>
238
+ `${r.stderr ?? ''}\n${r.stdout ?? ''}`
239
+ .split('\n')
240
+ .map((l) => l.trimEnd())
241
+ .filter((l) => l && !l.startsWith('hint:') && l !== 'Done')
242
+ .slice(-6)
243
+ .join('\n');
244
+
245
+ const AUTH = new RegExp(
246
+ [
247
+ 'terminal prompts disabled',
248
+ 'could not read (Username|Password)',
249
+ 'Authentication failed',
250
+ 'Invalid username or password',
251
+ 'Permission denied \\(publickey',
252
+ 'returned error: 40[13]',
253
+ ].join('|'),
254
+ 'i',
255
+ );
256
+
257
+ /** Why a network git failed, as a refusal a board acts on, or a plain error with git's words. */
258
+ export function netFailure(r, t, move, ms = NET_TIMEOUT_MS) {
259
+ const words = said(r);
260
+ if (r.timedOut)
261
+ return refusal(
262
+ 'timeout',
263
+ {},
264
+ `${move}: stopped after ${Math.round(ms / 1000)} s: git may be waiting for a password, or ` +
265
+ 'for a sign-in window on this PC',
266
+ );
267
+ if (AUTH.test(words))
268
+ return refusal(
269
+ 'auth',
270
+ {},
271
+ `${move}: git could not sign in to ${t.remote}. Push once from a terminal so the system ` +
272
+ `keeps the credential, then ${move} here.\n${words}`,
273
+ );
274
+
275
+ return new Error(`${move}: git failed\n${words}`);
276
+ }
277
+
278
+ /** A failed push: `!` lines of the porcelain say which ref and why; a pre-push hook says none. */
279
+ function pushFailure(r, t, ms) {
280
+ const bad = (r.stdout ?? '').split('\n').filter((l) => l.startsWith('!'));
281
+ if (bad.some((l) => /\((non-fast-forward|fetch first)\)/.test(l)))
282
+ return refusal(
283
+ 'behind',
284
+ {},
285
+ `Not pushed: ${t.short} has commits this branch lacks. Pull them first ` +
286
+ '(ai-factory gcf changes pull), or ask the agent to merge them',
287
+ );
288
+ if (!r.timedOut && (bad.length || /failed to push some refs/.test(r.stderr ?? '')))
289
+ return refusal('rejected', {}, `Not pushed: refused\n${said(r)}`);
290
+
291
+ return netFailure(r, t, 'push', ms);
292
+ }
293
+
294
+ /**
295
+ * Push the main checkout's branch, fast-forward only (p6): no `+`, no `--force*`, no
296
+ * `--no-verify`. No main lock: a push changes no file, and git updates the refs atomically.
297
+ * @param {string} dir
298
+ * @param {{remote?: string, timeoutMs?: number}} [opts]
299
+ */
300
+ export async function pushBranch(dir, { remote, timeoutMs = NET_TIMEOUT_MS } = {}) {
301
+ const branch = refuseWhereNoPush(dir, 'push');
302
+ const t = targetOf(dir, branch, remote);
303
+ const before = hashOf(dir, t.track);
304
+ const to = hashOf(dir, 'HEAD');
305
+ const pushed = count(
306
+ dir,
307
+ before ? ['HEAD', `^${before}`] : ['HEAD', '--not', `--remotes=${t.remote}`],
308
+ );
309
+ const r = await netGit(
310
+ dir,
311
+ [
312
+ 'push',
313
+ '--porcelain',
314
+ ...(t.set_upstream ? ['-u'] : []),
315
+ t.remote,
316
+ `refs/heads/${branch}:${t.ref}`,
317
+ ],
318
+ timeoutMs,
319
+ );
320
+ if (r.status !== 0) throw pushFailure(r, t, timeoutMs);
321
+
322
+ return {
323
+ remote: t.remote,
324
+ branch,
325
+ upstream: t.short,
326
+ from: before?.slice(0, 7) ?? null,
327
+ to: to.slice(0, 7),
328
+ pushed,
329
+ set_upstream: t.set_upstream,
330
+ };
331
+ }
332
+
333
+ /** The fast-forward under the main lock: the branch and its HEAD as they were checked. */
334
+ async function fastForward(dir, branch, head, theirs) {
335
+ return withMainLock(dir, async () => {
336
+ if (line(dir, 'symbolic-ref', '--short', '-q', 'HEAD') !== branch || operationInProgress(dir))
337
+ throw new Error(`pull: the checkout moved off ${branch} meanwhile: nothing pulled`);
338
+ if (hashOf(dir, 'HEAD') !== head)
339
+ throw new Error(`pull: ${branch} got a commit meanwhile: pull again`);
340
+ const r = git(dir, ['merge', '--ff-only', '--no-edit', theirs]);
341
+ if (r.status !== 0) throw new Error(`pull: git did not fast-forward\n${said(r)}`);
342
+ });
343
+ }
344
+
345
+ /**
346
+ * Pull the push target into the main checkout, fast-forward only (p9): a branch with commits of its
347
+ * own over the remote's is `diverged`, the agent's merge. It changes the working tree, so it claims
348
+ * the checkout as a build by click does: a run does not start meanwhile. The fetch lands in the
349
+ * target's tracking ref, not only FETCH_HEAD, which any other fetch may rewrite meanwhile.
350
+ * @param {string} dir
351
+ * @param {{remote?: string, timeoutMs?: number}} [opts]
352
+ */
353
+ export async function pullBranch(dir, { remote, timeoutMs = NET_TIMEOUT_MS } = {}) {
354
+ const branch = refuseWhereNoPush(dir, 'pull');
355
+ const t = targetOf(dir, branch, remote);
356
+ const release = await withMainLock(dir, () => claimMainRun(dir));
357
+ if (!release) throw refusal('running', {}, 'cannot pull while a run writes in the main checkout');
358
+ try {
359
+ const f = await netGit(
360
+ dir,
361
+ ['fetch', '--no-tags', t.remote, `+${t.ref}:${t.track}`],
362
+ timeoutMs,
363
+ );
364
+ if (f.status !== 0) throw netFailure(f, t, 'pull', timeoutMs);
365
+ const theirs = hashOf(dir, t.track);
366
+ const head = hashOf(dir, 'HEAD');
367
+ const base = { remote: t.remote, branch, upstream: t.short, from: head.slice(0, 7) };
368
+ const ancestor = (a, b) => git(dir, ['merge-base', '--is-ancestor', a, b]).status === 0;
369
+ if (ancestor(theirs, head)) return { ...base, to: head.slice(0, 7), pulled: 0 };
370
+ if (!ancestor(head, theirs))
371
+ throw refusal(
372
+ 'diverged',
373
+ {},
374
+ `Not pulled: ${branch} and ${t.short} each have commits the other lacks: a merge is the ` +
375
+ "agent's (git pull --no-rebase), main is untouched",
376
+ );
377
+ const pulled = count(dir, [theirs, `^${head}`]);
378
+ await fastForward(dir, branch, head, theirs);
379
+
380
+ return { ...base, to: theirs.slice(0, 7), pulled };
381
+ } finally {
382
+ await release();
383
+ }
384
+ }
@@ -0,0 +1,33 @@
1
+ // The environment a project's command runs in (`dod.*`, `play.build`, a target's start and stop).
2
+ // On Windows cmd.exe finds `bash` by PATH, and outside Git Bash the first one is System32's WSL
3
+ // launcher, which fails with no distribution. The agent finds and tries the project's commands in
4
+ // Git Bash: Git's own `bin` first in PATH gives them the same `bash` and `sh` from a board started
5
+ // in PowerShell, from a console and from a run. That folder holds bash, sh and git alone, so a
6
+ // command written for cmd.exe finds nothing else in it.
7
+ import { spawnSync } from 'node:child_process';
8
+ import { existsSync } from 'node:fs';
9
+ import path from 'node:path';
10
+
11
+ let gitBin;
12
+
13
+ /** Git for Windows' `bin`, found by the git on PATH; null off Windows or with no such Git. */
14
+ export function gitBinDir() {
15
+ if (process.platform !== 'win32') return null;
16
+ if (gitBin !== undefined) return gitBin;
17
+ const res = spawnSync('git', ['--exec-path'], { encoding: 'utf8', windowsHide: true });
18
+ // `<git>/mingw64/libexec/git-core`: its `bin` is three folders up.
19
+ const exec = res.status === 0 ? res.stdout.trim() : '';
20
+ const bin = exec ? path.resolve(exec, '..', '..', '..', 'bin') : null;
21
+ gitBin = bin && existsSync(path.join(bin, 'bash.exe')) ? bin : null;
22
+
23
+ return gitBin;
24
+ }
25
+
26
+ /** `env` with Git's `bin` first in its PATH on Windows; as it is elsewhere. */
27
+ export function commandEnv(env = process.env) {
28
+ const bin = gitBinDir();
29
+ if (!bin) return env;
30
+ const key = Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH';
31
+
32
+ return { ...env, [key]: `${bin}${path.delimiter}${env[key] ?? ''}` };
33
+ }
package/lib/verify.js CHANGED
@@ -7,6 +7,7 @@ import path from 'node:path';
7
7
  import { readConfig } from './gcf-paths.js';
8
8
  import { readLive, applyDelta } from './live.js';
9
9
  import { gateProblems } from './gate.js';
10
+ import { commandEnv } from './shell-env.js';
10
11
 
11
12
  /**
12
13
  * Every process's parent, `[pid, ppid]` (POSIX): from /proc on Linux, which a slim image has
@@ -83,7 +84,7 @@ function stopChildren(doomed) {
83
84
  */
84
85
  export function runCommand(cmd, cwd, stdio, ms) {
85
86
  return new Promise((resolve) => {
86
- const child = spawn(cmd, { cwd, shell: true, stdio });
87
+ const child = spawn(cmd, { cwd, shell: true, stdio, env: commandEnv() });
87
88
  let timedOut = false;
88
89
  const timer =
89
90
  ms > 0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.26.0",
3
+ "version": "0.27.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -35,6 +35,8 @@ forbidden_behaviors:
35
35
  - do not set `remove` of `propose_verdict_kill`, `propose_decide_no` or `propose_decide_wontfix`: the rule decides it, as in the human's form; `true` or `false` only on the human's words; the graveyard `tags` only on the human's words too
36
36
  - do not commit, discard or stash the human's hand edits under `gcf/`: they are the human's unfinished work; a move refused for them waits for the human, and `ai-factory gcf edits diff --path <path>` shows them
37
37
  - do not write code or edit files to fix what the talk finds: a fix is a work item, and its run builds it
38
+ - do not push or pull unless the human asks, and never force: `ai-factory gcf changes push` and `gcf changes pull` are the board's Push and Pull
39
+ - do not push again after a `behind` or `diverged` refusal until you ran `git pull --no-rebase`, resolved its conflicts, checked the build, and the human said so; on `auth` or `timeout` ask the human once to push from a terminal
38
40
  - do not answer from memory what a file says: read the file, then answer
39
41
  - do not ask again for a move the human refused: say what it would have done and leave it
40
42
  - do not read the board's own folder: it holds the human's token
@@ -103,6 +103,9 @@ gcf_work:
103
103
  - a move the commit gate refuses ends its error with `gcf-refusal: {"code":"gate","problems":[…]}`: git holds no commit of it; fix what it names, then make the move again
104
104
  - `ai-factory gcf changes [--worktree <id>]` lists what is uncommitted in the checkout or an item's worktree, `gcf changes diff --path <path>` shows one text file's diff
105
105
  - `gcf changes commit` is the human's Commit on the board, never the agent's; asked to commit loose work, read each diff and commit with git what belongs to the project
106
+ - `ai-factory gcf changes push` and `gcf changes pull` are the board's Push and Pull: push or pull only when the human asks, and never force
107
+ - a push refused with `gcf-refusal: {"code":"behind"}` or a pull with `{"code":"diverged"}`: run `git pull --no-rebase`, resolve the conflicts, check the build and the tests, then push again on the human's word
108
+ - a push refused with `{"code":"auth"}` or `{"code":"timeout"}`: ask the human, once, to push from a terminal so the system keeps the credential
106
109
  - `no_diff` in `gcf/config.yml` is the project's list of files shown without a diff
107
110
  - a chat thread bound to an item reads the item's file, its plan, its run's log and run chat first (the paths its context names), answers the question, and only then proposes a move
108
111