@smartmemory/compose 0.2.29-beta → 0.2.31-beta

package/bin/compose.js

@@ -120,6 +120,7 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  roadmap migrate    Extract ROADMAP.md entries into feature.json files')
   console.log('  roadmap check      Verify feature.json and ROADMAP.md are in sync')
   console.log('  roadmap xref-sync  Pull-reconcile feature.json external links to live state')
+  console.log('  roadmap xref-push  Push-write GitHub trackers to match expect= (dry-run; --apply to write)')
   console.log('  items              List vision items from local state (no server)')
   console.log('  items show <id>    Show detail for a specific vision item')
   console.log('  triage    Analyze a feature and recommend build profile')
@@ -1154,6 +1155,31 @@ if (cmd === 'roadmap') {
     process.exit(0)
   }
 
+  // compose roadmap xref-push — write GitHub trackers to match feature.json
+  // expect= declared intent (COMP-ROADMAP-XREF-PUSH v1). Dry-run by default,
+  // per-ref push:true opt-in, --apply to mutate. Degrade-skip, never guesses.
+  if (subcmd === 'xref-push') {
+    const { pushExternalRefs } = await import('../lib/xref-push.js')
+    const { root: cwd } = resolveCwdWithWorkspace(args)
+    const apply = args.includes('--apply')
+    const res = await pushExternalRefs(cwd, { apply })
+    const verb = apply ? 'wrote' : 'would write'
+    if (res.pushed.length === 0) {
+      console.log(`No external trackers to push (${res.scanned} push-opted link(s) checked, ${res.unchanged} already in sync).`)
+    } else {
+      console.log(`${apply ? 'Pushed' : 'Would push'} ${res.pushed.length} external tracker(s):`)
+      for (const s of res.pushed) console.log(`  ${s.code}  github ${s.target}: ${s.from} → ${s.to} (${verb})`)
+    }
+    if (res.skipped.length > 0) {
+      console.log(`\nSkipped ${res.skipped.length} link(s):`)
+      for (const s of res.skipped) console.log(`  ${s.code}  github ${s.target}: ${s.reason}`)
+    }
+    if (!apply && res.pushed.length > 0) {
+      console.log(`\nDry-run — pass --apply to write these changes to GitHub.`)
+    }
+    process.exit(0)
+  }
+
   // compose roadmap graph — generate a self-contained dependency-graph HTML
   // from feature.json + deps.yaml + frontmatter (COMP-ROADMAP-GRAPH-1).
   if (subcmd === 'graph') {

package/contracts/feature-json.schema.json

@@ -76,7 +76,8 @@
           "repo": { "type": "string" },
           "issue": { "type": "integer", "minimum": 1 },
           "url": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]*://" },
-          "expect": { "type": "string" }
+          "expect": { "type": "string" },
+          "push": { "type": "boolean" }
         },
         "allOf": [
           {

package/lib/feature-writer.js

@@ -841,6 +841,9 @@ function validateExternalArgs(args) {
     if (args.expect != null && !XREF_GITHUB_EXPECT.has(args.expect)) {
       throw new Error(`feature-writer: external github expect must be open|closed, got "${args.expect}"`);
     }
+    if (args.push != null && typeof args.push !== 'boolean') {
+      throw new Error(`feature-writer: external github push must be boolean, got "${args.push}"`);
+    }
   } else if (p === 'local') {
     if (!args.repo || !args.to_code) {
       throw new Error('feature-writer: external local link requires repo + to_code');
@@ -919,6 +922,7 @@ async function linkFeatureExternal(cwd, args) {
     if (args.to_code != null) entry.to_code = args.to_code;
     if (args.url != null) entry.url = args.url;
     if (args.expect != null) entry.expect = args.expect;
+    if (args.push != null) entry.push = args.push;
     if (args.note) entry.note = args.note;
 
     if (matchIdx !== -1) links[matchIdx] = entry;

package/lib/roadmap-graph/model.js

@@ -21,9 +21,14 @@ const STATUS_MAP = {
 };
 
 export class DanglingEdgeError extends Error {
-  /** @param {{from:string,to:string,kind:string}[]} dangling */
+  /** @param {{from:string,to:string,kind:string,missing:string[]}[]} dangling */
   constructor(dangling) {
-    const lines = dangling.map((d) => `  ${d.from} --${d.kind}--> ${d.to}  (${d.to} is not a known feature)`);
+    const lines = dangling.map((d) => {
+      const missing = d.missing && d.missing.length ? d.missing : [d.to];
+      const what = missing.length > 1 ? `${missing.join(', ')} are not known features`
+        : `${missing[0]} is not a known feature`;
+      return `  ${d.from} --${d.kind}--> ${d.to}  (${what})`;
+    });
     super(`roadmap-graph: refusing to emit — ${dangling.length} dangling edge(s):\n${lines.join('\n')}`);
     this.code = 'DANGLING_EDGE';
     this.dangling = dangling;
@@ -72,7 +77,10 @@ export function buildGraph({ nodes, rawEdges, knownCodes }) {
     const fromUnknown = !known.has(e.from);
     const toUnknown = !known.has(e.to);
     if (fromUnknown || toUnknown) {
-      dangling.push({ from: e.from, to: e.to, kind: e.type });
+      const missing = [];
+      if (fromUnknown) missing.push(e.from);
+      if (toUnknown) missing.push(e.to);
+      dangling.push({ from: e.from, to: e.to, kind: e.type, missing });
       continue;
     }
     // Known but not rendered (dropped by status) -> silently drop the edge.

package/lib/tracker/github-api.js

@@ -50,6 +50,14 @@ export class GitHubApi {
    */
   async getIssueResult(number) { return this._req('GET', `/repos/${this.repo}/issues/${number}`); }
   async updateIssue(number, patch) { return (await this._req('PATCH', `/repos/${this.repo}/issues/${number}`, patch)).body; }
+  /**
+   * PATCH /repos/:repo/issues/:number — status-returning sibling of updateIssue().
+   * Returns { status, body, headers }; does NOT throw on 4xx (mirrors
+   * getIssueResult()). Used by COMP-ROADMAP-XREF-PUSH to distinguish a real write
+   * from 403/404/422 so a failed write degrades to a skip, never a false success.
+   * updateIssue() untouched.
+   */
+  async updateIssueResult(number, patch) { return this._req('PATCH', `/repos/${this.repo}/issues/${number}`, patch); }
   async searchFeatureIssues() {
     return (await this._req('GET', `/search/issues?q=repo:${this.repo}+label:compose-feature`)).body.items ?? [];
   }

package/lib/xref-push.js

@@ -0,0 +1,179 @@
+/**
+ * xref-push.js — COMP-ROADMAP-XREF-PUSH v1 (PUSH reconciliation).
+ *
+ * The write-side counterpart to xref-sync.js (PULL). Pull rewrites the LOCAL
+ * citation's `expect=` to match EXTERNAL reality; Push does the inverse — it
+ * writes the EXTERNAL tracker (a GitHub issue's open/closed state) to match the
+ * locally-declared `expect=` intent. Because this mutates a system outside the
+ * repo it is dry-run by default, opt-in per ref (`push: true` on the link), and
+ * degrades (never writes, never guesses) on any resolution or write failure —
+ * exactly mirroring xref-sync's degrade posture.
+ *
+ * Operates on the structured `links[].kind === 'external'` carrier and NEVER
+ * mutates feature.json: `expect` is the unchanged source of intent. Resolution
+ * and the external write are both injectable for testability (no network in
+ * tests). github provider only in v1.
+ */
+
+import { readdirSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { loadFeaturesDir } from './project-paths.js';
+
+const GITHUB_STATES = new Set(['open', 'closed']);
+
+/** Is `s` a writable GitHub issue state? */
+export function isGithubState(s) {
+  return GITHUB_STATES.has(s);
+}
+
+/**
+ * Pure mirror of reconcileExpect (xref-sync.js): should the external be written
+ * to match `ref.expect`, given its current `liveState`?
+ *
+ * @param {{expect: string|null}} ref
+ * @param {string|null} liveState  resolved current external state, or null if unresolved
+ * @returns {{action: 'none'|'write', from?: string, to?: string}}
+ */
+export function planPush(ref, liveState) {
+  if (!ref.expect) return { action: 'none' };          // no declared intent
+  if (liveState == null) return { action: 'none' };    // unresolved → leave alone
+  if (ref.expect === liveState) return { action: 'none' }; // idempotent
+  return { action: 'write', from: liveState, to: ref.expect };
+}
+
+/**
+ * Build a GitHubApi for `link`, or return a degrade reason. `transport`/`auth`
+ * are injectable (mirrors feature-validator's githubTransport/githubAuth) so the
+ * real resolve/write degrade paths are testable without network.
+ * @returns {{gh}|{skipped: true, reason: string}}
+ */
+async function makeClient(link, { transport = null, auth } = {}) {
+  let GitHubApi;
+  try { ({ GitHubApi } = await import('./tracker/github-api.js')); }
+  catch (e) { return { skipped: true, reason: `github client unavailable: ${e.message}` }; }
+  const a = auth ?? { token: process.env.GITHUB_TOKEN || process.env.GH_TOKEN };
+  try {
+    return { gh: new GitHubApi({ repo: link.repo, auth: a }, transport) };
+  } catch (e) {
+    return { skipped: true, reason: (e && e.message) || 'no GitHub auth' };
+  }
+}
+
+/**
+ * Resolve a github link to its current state. Mirrors xref-sync's defaultResolve
+ * degrade semantics AND additionally rejects pull-request-backed refs (a state
+ * PATCH would close/reopen a PR — GitHub's Issues API treats PRs as issues).
+ * Returns { state } on success, or { skipped, reason } on any degrade.
+ */
+export async function defaultResolve(link, opts = {}) {
+  if (!link.repo || link.issue == null) return { skipped: true, reason: 'incomplete github ref' };
+  const c = await makeClient(link, opts);
+  if (c.skipped) return c;
+  try {
+    const r = await c.gh.getIssueResult(link.issue);
+    if (r.status === 404) return { skipped: true, reason: `target ${link.repo}#${link.issue} missing (404)` };
+    if (r.status < 200 || r.status >= 300) return { skipped: true, reason: `HTTP ${r.status}` };
+    if (r.body && r.body.pull_request) {
+      return { skipped: true, reason: `${link.repo}#${link.issue} is a pull request, not an issue` };
+    }
+    const state = r.body && r.body.state;
+    if (!isGithubState(state)) return { skipped: true, reason: 'no parseable issue state' };
+    return { state };
+  } catch (e) {
+    return { skipped: true, reason: e && e.rateLimit ? 'rate limit' : (e && e.message) || 'resolution error' };
+  }
+}
+
+/**
+ * Write a github link's issue to `toState`. Uses updateIssueResult (status-
+ * returning) so a non-2xx response degrades to a skip rather than a false
+ * success. Returns { ok: true } or { skipped, reason }.
+ */
+export async function defaultWrite(link, toState, opts = {}) {
+  if (!link.repo || link.issue == null) return { skipped: true, reason: 'incomplete github ref' };
+  const c = await makeClient(link, opts);
+  if (c.skipped) return c;
+  try {
+    const r = await c.gh.updateIssueResult(link.issue, { state: toState });
+    if (r.status < 200 || r.status >= 300) return { skipped: true, reason: `write HTTP ${r.status}` };
+    return { ok: true };
+  } catch (e) {
+    return { skipped: true, reason: e && e.rateLimit ? 'rate limit' : (e && e.message) || 'write error' };
+  }
+}
+
+/**
+ * Push-write every eligible feature.json external link's target to match its
+ * declared `expect`. Eligibility: github provider, `push === true`, and a valid
+ * github `expect` state. Dry-run unless `apply` is true. NEVER mutates feature.json.
+ *
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {boolean} [opts.apply]       perform writes (default false = dry-run)
+ * @param {string}  [opts.featuresDir]
+ * @param {(link: object) => Promise<{state?: string, skipped?: boolean, reason?: string}>} [opts.resolve]
+ * @param {(link: object, toState: string) => Promise<{ok?: boolean, skipped?: boolean, reason?: string}>} [opts.write]
+ * @param {object} [opts.githubTransport]  injectable transport for the default resolve/write (tests)
+ * @param {object} [opts.githubAuth]       injectable auth for the default resolve/write (tests)
+ * @returns {Promise<{pushed: Array, skipped: Array, unchanged: number, scanned: number}>}
+ */
+export async function pushExternalRefs(cwd, opts = {}) {
+  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const clientOpts = { transport: opts.githubTransport ?? null, auth: opts.githubAuth };
+  const resolve = opts.resolve ?? ((link) => defaultResolve(link, clientOpts));
+  const write = opts.write ?? ((link, toState) => defaultWrite(link, toState, clientOpts));
+  const apply = opts.apply === true;
+  const dir = join(cwd, featuresDir);
+
+  const pushed = [];
+  const skipped = [];
+  let unchanged = 0;
+  let scanned = 0;
+
+  if (!existsSync(dir)) return { pushed, skipped, unchanged, scanned };
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const fjPath = join(dir, entry.name, 'feature.json');
+    if (!existsSync(fjPath)) continue;
+    let fj;
+    try { fj = JSON.parse(readFileSync(fjPath, 'utf8')); } catch { continue; }
+    if (!Array.isArray(fj.links)) continue;
+
+    for (const link of fj.links) {
+      if (!link || link.kind !== 'external') continue;
+      // v1: github only, opt-in only, valid target state only.
+      if (link.provider !== 'github' || link.push !== true) continue;
+      scanned++;
+      if (!isGithubState(link.expect)) {
+        skipped.push({ code: fj.code, target: targetLabel(link), reason: `malformed expect "${link.expect}" (want open|closed)` });
+        continue;
+      }
+
+      const r = await resolve(link);
+      if (r.skipped) {
+        skipped.push({ code: fj.code, target: targetLabel(link), reason: r.reason });
+        continue;
+      }
+      const verdict = planPush(link, r.state ?? null);
+      if (verdict.action !== 'write') { unchanged++; continue; }
+
+      if (!apply) {
+        pushed.push({ code: fj.code, target: targetLabel(link), from: verdict.from, to: verdict.to });
+        continue;
+      }
+      const w = await write(link, verdict.to);
+      if (w.skipped) {
+        skipped.push({ code: fj.code, target: targetLabel(link), reason: w.reason });
+        continue;
+      }
+      pushed.push({ code: fj.code, target: targetLabel(link), from: verdict.from, to: verdict.to });
+    }
+  }
+
+  return { pushed, skipped, unchanged, scanned };
+}
+
+function targetLabel(link) {
+  return `${link.repo}#${link.issue}`;
+}

package/lib/xref-sync.js

@@ -130,7 +130,10 @@ export async function syncExternalRefs(cwd, opts = {}) {
     for (const link of fj.links) {
       if (!link || link.kind !== 'external') continue;
       // Only resolvable providers that carry an explicit expectation can drift.
-      if (!RESOLVABLE.has(link.provider) || !link.expect) continue;
+      // Push-managed links (push:true, COMP-ROADMAP-XREF-PUSH) are owned by the
+      // write side — pulling them would clobber the declared intent before push
+      // runs, so a link is either pull-managed or push-managed, never both.
+      if (!RESOLVABLE.has(link.provider) || !link.expect || link.push === true) continue;
       scanned++;
 
       const r = await resolve(link, cwd, featuresDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.29-beta",
+  "version": "0.2.31-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",