forge-workflow 0.1.0-beta.5 → 0.1.0-beta.7

package/lib/forge-issues.js

@@ -7,6 +7,8 @@ const { createLocalBroker, buildLocalBrokerConfig } = require('./kernel/broker')
 const { createBuiltinSQLiteDriver } = require('./kernel/sqlite-driver');
 const { detectWorktree } = require('./detect-worktree');
 const { DEFAULT_LEASE_TTL_MS } = require('./kernel/lease-enforcer');
+const { ISSUE_TYPES } = require('./kernel/issue-command-contract');
+const { loadRuntimeGraphConfig } = require('./core/runtime-graph');
 
 const OPERATION_METHOD_ALIASES = {
   'dep.add': 'depAdd',
@@ -199,6 +201,75 @@ function resolveLeaseTtlMs(env = {}) {
   return ttl;
 }
 
+function readIssueContractValues(loaded, fail) {
+	const missing = Symbol('missing issue contract config');
+	const ownDataValue = (object, key, path) => {
+		if (!object || (typeof object !== 'object' && typeof object !== 'function')) return missing;
+		const descriptor = Object.getOwnPropertyDescriptor(object, key);
+		if (!descriptor) return missing;
+		if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+			fail(`${path} must be a data property`);
+		}
+		return descriptor.value;
+	};
+	const issues = ownDataValue(loaded?.config, 'issues', 'issues');
+	const readiness = issues === missing ? missing : ownDataValue(issues, 'readiness', 'issues.readiness');
+	const configured = readiness === missing
+		? missing
+		: ownDataValue(readiness, 'contracts', 'issues.readiness.contracts');
+	if (configured === missing || configured == null) return null;
+	if (typeof configured !== 'object'
+		|| Array.isArray(configured)
+		|| Object.getPrototypeOf(configured) !== Object.prototype) {
+		fail('issues.readiness.contracts must be a plain JSON object');
+	}
+	const allowedKeys = new Set(['enabled', 'workClasses']);
+	const ownKeys = Reflect.ownKeys(configured);
+	const unknownKeys = ownKeys.filter(key => typeof key !== 'string' || !allowedKeys.has(key));
+	if (unknownKeys.length > 0) {
+		fail(`unknown issues.readiness.contracts keys: ${unknownKeys.map(String).sort((left, right) => left.localeCompare(right)).join(', ')}`);
+	}
+	const values = Object.create(null);
+	for (const key of ownKeys) {
+		const descriptor = Object.getOwnPropertyDescriptor(configured, key);
+		if (!descriptor || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+			fail(`issues.readiness.contracts.${key} must be a data property`);
+		}
+		values[key] = descriptor.value;
+	}
+	return values;
+}
+
+function resolveIssueContractPolicy(projectRoot, deps = {}) {
+	const loadConfig = deps.loadRuntimeGraphConfig || loadRuntimeGraphConfig;
+	const loaded = loadConfig({ projectRoot });
+	const fail = message => {
+		const error = new Error(`FORGE_ISSUE_CONTRACT_CONFIG_INVALID: ${message}`);
+		error.code = 'FORGE_ISSUE_CONTRACT_CONFIG_INVALID';
+		throw error;
+	};
+	if (Array.isArray(loaded?.errors) && loaded.errors.length > 0) {
+		fail(loaded.errors.map(error => error.message || error.code || String(error)).join('; '));
+	}
+	const values = readIssueContractValues(loaded, fail);
+	if (values === null) return null;
+	if (values.enabled !== undefined && typeof values.enabled !== 'boolean') {
+		fail('issues.readiness.contracts.enabled must be a boolean');
+	}
+	if (values.enabled !== true) return { enabled: false, workClasses: [] };
+	if (!Array.isArray(values.workClasses) || values.workClasses.length === 0) {
+		fail('issues.readiness.contracts.workClasses must be a non-empty array');
+	}
+	const allowedClasses = new Set(ISSUE_TYPES);
+	if (values.workClasses.some(value => typeof value !== 'string' || !allowedClasses.has(value))) {
+		fail('issues.readiness.contracts.workClasses contains an unknown work class');
+	}
+	return {
+		enabled: true,
+		workClasses: [...new Set(values.workClasses)],
+	};
+}
+
 async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
   const injectedService = deps.createService;
 
@@ -206,6 +277,7 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
     backend: createKernelIssueBackend({ projectRoot, deps }),
   }));
 
+  const contractPolicy = resolveIssueContractPolicy(projectRoot, deps);
   const service = createService();
   // Thread a distinct per-agent actor (and, when present, a stable session id) into the
   // mutation context so the Kernel's claim idempotency key is scoped per agent rather than
@@ -223,6 +295,9 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
   const isClaim = operation === 'claim';
   const worktreeId = isClaim ? resolveWorktreeId(projectRoot, actorEnv, deps) : undefined;
   const leaseTtlMs = isClaim ? resolveLeaseTtlMs(actorEnv) : undefined;
+	const isTrustedAdoption = typeof deps.verifyIssueContractAdoption === 'function'
+		? deps.verifyIssueContractAdoption
+		: undefined;
   try {
     const result = await service.run(operation, rawArgs, {
       projectRoot,
@@ -231,6 +306,8 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
       ...(sessionId ? { sessionId } : {}),
       ...(worktreeId ? { worktreeId } : {}),
       ...(leaseTtlMs ? { leaseTtlMs } : {}),
+		...(contractPolicy ? { contractPolicy } : {}),
+		...(isTrustedAdoption ? { isTrustedAdoption } : {}),
       // Kernel mutations enqueue a projection-outbox "dirty marker" that `forge export`
       // (the D16 git-JSONL portability projection) drains under target 'jsonl'. The
       // broker's legacy primitive default is still 'beads', so without steering the target
@@ -267,4 +344,5 @@ module.exports = {
   runIssueOperation,
   isHelpInvocation,
   resolveIssueActor,
+	resolveIssueContractPolicy,
 };

package/lib/gate-events.js

@@ -49,8 +49,13 @@ const GATE_EVENT_ORIGIN = 'cli';
  * SAME-actor re-approval mints no duplicate, while a later reject (different
  * decision) or a different actor is recorded as its own event.
  */
-function gateIdempotencyKey(eventType, issueId, gateId, actor) {
-  return `${eventType}:${issueId}:${gateId}:${actor}`;
+function gateIdempotencyKey(eventType, issueId, gateId, actor, expiresAt) {
+  const base = `${eventType}:${issueId}:${gateId}:${actor}`;
+  return expiresAt ? `${base}:${expiresAt}` : base;
+}
+
+function gateControlId(issueId, gateId) {
+  return `gate:${issueId}:${gateId}`;
 }
 
 /** Shape a stored kernel_events row into the gate-event view callers consume. */
@@ -67,6 +72,18 @@ function parseGateEvent(row) {
     actor: row.actor,
     created_at: row.created_at,
   };
+  // Older direct callers supplied only the legacy row subset and consumed its
+  // exact four-field view. Stored Kernel rows always carry entity_id, so enrich
+  // those audit/status views without changing that legacy parse contract.
+  if (row.entity_id) {
+    view.issue_id = row.entity_id;
+    view.control_id = payload.control_id || gateControlId(row.entity_id, payload.gate);
+    view.decision = row.event_type === GATE_APPROVED_EVENT ? 'approved' : 'rejected';
+    view.issued_at = row.created_at;
+    view.expires_at = payload.expires_at ?? null;
+    view.request_identity = payload.request_identity ?? null;
+    view.generation = Number.isInteger(payload.generation) ? payload.generation : 0;
+  }
   if (payload.reason !== undefined) view.reason = payload.reason;
   return view;
 }
@@ -76,10 +93,43 @@ function isIdempotencyRace(error) {
   return /UNIQUE constraint failed/i.test(message) && /idempotency_key/i.test(message);
 }
 
+function isActiveApproval(event, now) {
+  if (!event || event.event_type !== GATE_APPROVED_EVENT) return false;
+  if (!event.expires_at) return true;
+  const nowMillis = Date.parse(now);
+  const expiryMillis = Date.parse(event.expires_at);
+  return Number.isFinite(nowMillis) && Number.isFinite(expiryMillis) && nowMillis < expiryMillis;
+}
+
+function planGateGeneration(events, params) {
+  const { gateId, decision, actor, requestIdentity, now } = params;
+  const gateEvents = events.filter(event => event.gate === gateId);
+  const latest = gateEvents.at(-1);
+  const maxGeneration = gateEvents.reduce(
+    (max, event) => Math.max(max, Number.isInteger(event.generation) ? event.generation : 0),
+    -1,
+  );
+
+  if (decision === 'approved') {
+    const identicalActive = latest
+      && latest.actor === actor
+      && latest.request_identity === requestIdentity
+      && isActiveApproval(latest, now);
+    if (identicalActive) return { duplicateEvent: latest, generation: latest.generation };
+    return { duplicateEvent: null, generation: maxGeneration + 1 };
+  }
+
+  if (latest?.event_type === GATE_REJECTED_EVENT && latest.actor === actor) {
+    return { duplicateEvent: latest, generation: latest.generation };
+  }
+  return { duplicateEvent: null, generation: Math.max(maxGeneration, 0) };
+}
+
 /**
- * Record a gate decision as a kernel event on the issue. Idempotent per
- * issue+gate+actor+decision. Validates the issue exists (the caller validates the
- * gate id against the known-gate set before calling).
+ * Record a gate decision as a kernel event on the issue. Active identical
+ * requests are idempotent; expiry/rejection advances the durable generation so
+ * a later approval can become authoritative. Validates the issue exists (the
+ * caller validates the gate id against the known-gate set before calling).
  *
  * @param {string} projectRoot
  * @param {Object} params
@@ -93,7 +143,7 @@ function isIdempotencyRace(error) {
  * @returns {Promise<{ ok: boolean, duplicate?: boolean, issueMissing?: boolean, event?: Object, actor?: string }>}
  */
 async function recordGateEvent(projectRoot, params = {}) {
-  const { issueId, gateId, decision, reason, env, deps, now } = params;
+  const { issueId, gateId, decision, reason, expiresAt, requestIdentity, env, deps, now } = params;
   const eventType = GATE_EVENT_TYPES[decision];
   if (!eventType) {
     throw new Error(`Unknown gate decision '${decision}' (expected 'approved' or 'rejected').`);
@@ -109,14 +159,42 @@ async function recordGateEvent(projectRoot, params = {}) {
       return { ok: false, issueMissing: true, actor };
     }
 
-    const idempotencyKey = gateIdempotencyKey(eventType, issueId, gateId, actor);
+    const createdAt = now || new Date().toISOString();
+    const stableRequestIdentity = requestIdentity ?? expiresAt ?? null;
+    const rows = await driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    const generationPlan = planGateGeneration((rows || []).map(parseGateEvent), {
+      gateId,
+      decision,
+      actor,
+      requestIdentity: stableRequestIdentity,
+      now: createdAt,
+    });
+    if (generationPlan.duplicateEvent) {
+      return { ok: true, duplicate: true, event: generationPlan.duplicateEvent, actor };
+    }
+    const keyParts = [stableRequestIdentity];
+    if (generationPlan.generation > 0) keyParts.push(`generation=${generationPlan.generation}`);
+    const idempotencyKey = gateIdempotencyKey(
+      eventType,
+      issueId,
+      gateId,
+      actor,
+      keyParts.filter(Boolean).join(':') || undefined,
+    );
 
     const existing = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
     if (existing) {
       return { ok: true, duplicate: true, event: parseGateEvent(existing), actor };
     }
 
-    const payload = { gate: gateId, actor };
+    const payload = {
+      gate: gateId,
+      actor,
+      control_id: gateControlId(issueId, gateId),
+      expires_at: expiresAt ?? null,
+      request_identity: stableRequestIdentity,
+      generation: generationPlan.generation,
+    };
     if (typeof reason === 'string' && reason.length > 0) payload.reason = reason;
 
     const event = {
@@ -128,7 +206,7 @@ async function recordGateEvent(projectRoot, params = {}) {
       actor,
       origin: GATE_EVENT_ORIGIN,
       payload,
-      created_at: now || new Date().toISOString(),
+      created_at: createdAt,
     };
 
     try {
@@ -166,6 +244,12 @@ async function listGateEvents(projectRoot, issueId, options = {}) {
   }
 }
 
+function evaluateGateApproval(events, gateId, now = new Date().toISOString()) {
+  const decisions = events.filter(event => event.gate === gateId);
+  const event = decisions.at(-1);
+  return { approved: isActiveApproval(event, now), event };
+}
+
 /**
  * True iff a `gate.approved` event exists for this issue + gate.
  *
@@ -177,7 +261,7 @@ async function listGateEvents(projectRoot, issueId, options = {}) {
  */
 async function isGateApproved(projectRoot, issueId, gateId, options = {}) {
   const events = await listGateEvents(projectRoot, issueId, options);
-  return events.some(event => event.event_type === GATE_APPROVED_EVENT && event.gate === gateId);
+  return evaluateGateApproval(events, gateId, options.now).approved;
 }
 
 module.exports = {
@@ -185,8 +269,12 @@ module.exports = {
   GATE_REJECTED_EVENT,
   GATE_EVENT_TYPES,
   gateIdempotencyKey,
+  gateControlId,
+  isActiveApproval,
+  planGateGeneration,
   parseGateEvent,
   recordGateEvent,
   listGateEvents,
+  evaluateGateApproval,
   isGateApproved,
 };

package/lib/github-context.js

@@ -0,0 +1,308 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const ACCOUNT_KEY = 'github.account';
+const HOST = 'github.com';
+const LOGIN_RE = /^(?=.{1,39}$)[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+const GITHUB_ENV_NAMES = new Set(['gh_token', 'github_token', 'gh_host', 'gh_repo']);
+const GITHUB_SECRET_ENV_NAMES = new Set(['gh_token', 'github_token']);
+
+class GithubContextError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'GithubContextError';
+    this.code = code;
+  }
+
+  toJSON() {
+    return { code: this.code, message: this.message };
+  }
+}
+
+function validateGithubLogin(login) {
+  return typeof login === 'string' && LOGIN_RE.test(login);
+}
+
+function safeLogin(login) {
+  return validateGithubLogin(login) ? login : null;
+}
+
+function runnerFor(options) {
+  return options.runner || options._runner || options._exec || options.execFileSync || defaultRunner;
+}
+
+function defaultRunner(command, args, options = {}) {
+  return execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+    ...options,
+  });
+}
+
+function errorText(error) {
+  return [error?.message, error?.stderr?.toString?.(), error?.stdout?.toString?.()]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+}
+
+function isUnsupportedTokenCapability(error) {
+  const text = errorText(error);
+  return /unknown (?:flag|option)|invalid (?:flag|option)|unexpected argument|does not support/.test(text)
+    && /user|hostname/.test(text);
+}
+
+function safeCommandFailure(code, message) {
+  return new GithubContextError(code, message);
+}
+
+function safeGithubCommandFailure(error) {
+  const text = errorText(error);
+  const failure = safeCommandFailure(
+    'GITHUB_COMMAND_FAILED',
+    /rate limit|secondary rate/.test(text)
+      ? 'The GitHub CLI command was rate limited.'
+      : 'The GitHub CLI command failed without exposing its output.',
+  );
+  const matchedStatus = /\bhttp\s+(401|403|429)\b/.exec(text)?.[1];
+  let httpStatus;
+  if ([401, 403, 429].includes(error?.httpStatus)) httpStatus = error.httpStatus;
+  else if ([401, 403, 429].includes(error?.status)) httpStatus = error.status;
+  else httpStatus = Number(matchedStatus) || undefined;
+  const retryAfter = Number(error?.retryAfter);
+  if (httpStatus) failure.httpStatus = httpStatus;
+  if (Number.isFinite(retryAfter) && retryAfter > 0) failure.retryAfter = retryAfter;
+  return failure;
+}
+
+function gitConfig(projectRoot, args, options, absentIsOkay = false) {
+  try {
+    return runnerFor(options)('git', ['config', '--local', ...args], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (absentIsOkay && (error?.status === 1 || /key does not contain|not found|no such key/i.test(errorText(error)))) {
+      return '';
+    }
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to read this clone-local GitHub account binding.');
+  }
+}
+
+function readGithubAccount(projectRoot, options = {}) {
+  const output = gitConfig(projectRoot, ['--get', ACCOUNT_KEY], options, true);
+  const value = output == null ? '' : output.toString().trim();
+  return value || null;
+}
+
+function writeGithubAccount(projectRoot, login, options = {}) {
+  if (!validateGithubLogin(login)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  try {
+    runnerFor(options)('git', ['config', '--local', '--replace-all', ACCOUNT_KEY, login], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (_error) {
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to write the clone-local GitHub account binding.');
+  }
+}
+
+function unsetGithubAccount(projectRoot, options = {}) {
+  try {
+    runnerFor(options)('git', ['config', '--local', '--unset-all', ACCOUNT_KEY], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (error?.status === 5 || /key does not contain|not found|no such key/i.test(errorText(error))) return;
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to remove the clone-local GitHub account binding.');
+  }
+}
+
+function withoutGithubEnvironment(environment) {
+  const result = {};
+  for (const [key, value] of Object.entries(environment || {})) {
+    if (!GITHUB_ENV_NAMES.has(key.toLowerCase())) result[key] = value;
+  }
+  return result;
+}
+
+function selectedEnvironment(baseEnv, token, additions = {}) {
+  const result = withoutGithubEnvironment(baseEnv);
+  Object.assign(result, withoutGithubEnvironment(additions));
+  result.GH_TOKEN = token;
+  result.GITHUB_TOKEN = token;
+  result.GH_HOST = HOST;
+  return result;
+}
+
+function passthroughEnvironment(baseEnv, additions = {}) {
+  return { ...baseEnv, ...additions };
+}
+
+function retrieveGithubToken(login, options) {
+  if (!validateGithubLogin(login)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  const baseEnv = options.baseEnv || options.env || process.env;
+  let output;
+  try {
+    output = runnerFor(options)('gh', ['auth', 'token', '--hostname', HOST, '--user', login], {
+      env: withoutGithubEnvironment(baseEnv),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (isUnsupportedTokenCapability(error)) {
+      throw safeCommandFailure('GITHUB_CLI_UNSUPPORTED', 'Upgrade GitHub CLI, then authenticate the account with gh auth login.');
+    }
+    throw safeCommandFailure('GITHUB_NOT_AUTHENTICATED', 'GitHub account is not authenticated; run gh auth login for this account.');
+  }
+
+  const token = output == null ? '' : output.toString().trim();
+  if (!token) {
+    throw safeCommandFailure('GITHUB_NOT_AUTHENTICATED', 'GitHub account is not authenticated; run gh auth login for this account.');
+  }
+  return token;
+}
+
+function loginFromOutput(output) {
+  const text = output == null ? '' : output.toString().trim();
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return safeLogin(parsed?.login);
+  } catch {
+    // `gh --jq` normally returns plain text; JSON is only a compatibility path.
+    return safeLogin(text.split(/\r?\n/, 1)[0].trim());
+  }
+}
+
+function resolveGithubLogin(token, baseEnv, options) {
+  try {
+    const output = runnerFor(options)('gh', ['api', '--hostname', HOST, 'user', '--jq', '.login'], {
+      env: selectedEnvironment(baseEnv, token),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    const login = loginFromOutput(output);
+    if (!login) throw new Error('missing login');
+    return login;
+  } catch {
+    // Provider errors may contain response bodies or credentials; expose only a safe diagnosis.
+    throw safeCommandFailure('GITHUB_AUTH_FAILED', 'Unable to verify the selected GitHub account; run gh auth login and try again.');
+  }
+}
+
+function prepareGithubAccount(_projectRoot, account, options = {}) {
+  if (!validateGithubLogin(account)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  const baseEnv = { ...(options.baseEnv || options.env || process.env) };
+  const token = retrieveGithubToken(account, { ...options, baseEnv });
+  const login = resolveGithubLogin(token, baseEnv, options);
+  if (login.toLowerCase() !== account.toLowerCase()) {
+    throw safeCommandFailure('GITHUB_ACCOUNT_MISMATCH', `GitHub account mismatch: expected ${account}, received ${login}.`);
+  }
+  return createPublicContext(publicStatus('ready', account, login), token, baseEnv, options);
+}
+
+function publicStatus(state, account, login) {
+  return Object.freeze({ state, account: account || null, login: login || null });
+}
+
+function createPublicContext(status, token, baseEnv, options) {
+  const context = {
+    status,
+    bound: status.state !== 'unbound',
+    account: status.account,
+    login: status.login,
+  };
+  const secrets = (status.state === 'unbound'
+    ? Object.entries(baseEnv)
+      .filter(([key]) => GITHUB_SECRET_ENV_NAMES.has(key.toLowerCase()))
+      .map(([, value]) => value)
+    : [token])
+    .filter((value) => typeof value === 'string' && value);
+  const environmentForChild = (additions = {}) => status.state === 'unbound'
+    ? passthroughEnvironment(baseEnv, additions)
+    : selectedEnvironment(baseEnv, token, additions);
+  const childRunner = options.childRunner || options._childRunner || runnerFor(options);
+  const runChild = (command, args, runOptions = {}) => {
+    if (typeof command !== 'string' || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) {
+      throw safeCommandFailure('INVALID_GH_ARGUMENTS', 'GitHub CLI arguments must be an array of strings.');
+    }
+    try {
+      return childRunner(command, args, {
+        ...runOptions,
+        env: environmentForChild(runOptions.env),
+      });
+    } catch (_error) {
+      throw safeCommandFailure('GITHUB_COMMAND_FAILED', 'The GitHub CLI command failed without exposing its output.');
+    }
+  };
+  const runGh = (args, runOptions = {}) => {
+    if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) {
+      throw safeCommandFailure('INVALID_GH_ARGUMENTS', 'GitHub CLI arguments must be an array of strings.');
+    }
+    try {
+      const output = runnerFor(options)('gh', args, {
+        ...runOptions,
+        env: environmentForChild(runOptions.env),
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+      return redactTokens(output, secrets);
+    } catch (error) {
+      throw safeGithubCommandFailure(error);
+    }
+  };
+  Object.defineProperties(context, {
+    runChild: { value: runChild, enumerable: false },
+    runGh: { value: runGh, enumerable: false },
+    getStatus: { value: () => ({ ...status }), enumerable: false },
+  });
+  return context;
+}
+
+function redactTokens(value, tokens) {
+  if (value == null) return value;
+  return tokens.slice().sort((left, right) => right.length - left.length)
+    .reduce((redacted, token) => redacted.split(token).join('[REDACTED]'), value.toString());
+}
+
+function createGithubContext(projectRoot, options = {}) {
+  const baseEnv = { ...(options.baseEnv || options.env || process.env) };
+  const account = readGithubAccount(projectRoot, options);
+  if (!account) return createPublicContext(publicStatus('unbound', null, null), null, baseEnv, options);
+  if (!validateGithubLogin(account)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'The clone-local github.account value is not a valid GitHub login.');
+  }
+  return prepareGithubAccount(projectRoot, account, { ...options, baseEnv });
+}
+
+module.exports = {
+  ACCOUNT_KEY,
+  GithubContextError,
+  createGithubContext,
+  prepareGithubAccount,
+  prepareGithubContext: createGithubContext,
+  readGithubAccount,
+  resolveGithubLogin,
+  unsetGithubAccount,
+  validateGithubLogin,
+  writeGithubAccount,
+};

package/lib/global-flags.js

@@ -37,6 +37,7 @@ const GLOBAL_BOOLEAN_FLAGS = new Set([
   '--verbose',
   '--dry-run',
   '--symlink',
+  '--skills-only', '--no-hooks',
   '--sync',
   '--interview',
 ]);