@smartmemory/compose 0.1.34-beta → 0.1.35-beta

package/lib/feature-writer.js

@@ -19,13 +19,18 @@
 import { existsSync, realpathSync, statSync } from 'fs';
 import { resolve, normalize, sep, basename, dirname } from 'path';
 
-import { readFeature, writeFeature, listFeatures, updateFeature } from './feature-json.js';
-const _listFeatures = listFeatures;
-import { writeRoadmap } from './roadmap-gen.js';
-import { appendEvent, readEvents } from './feature-events.js';
+import { readEvents } from './feature-events.js';
 import { checkOrInsert } from './idempotency.js';
 import { loadFeaturesDir } from './project-paths.js';
 
+// providerFor is imported lazily (inside each function) to break the
+// module-load-time cycle: factory.js → local-provider.js → feature-writer.js.
+// Dynamic import resolves at call time, after all modules have loaded.
+async function getProvider(cwd) {
+  const { providerFor } = await import('./tracker/factory.js');
+  return providerFor(cwd);
+}
+
 // ---------------------------------------------------------------------------
 // Status / transition policy
 // ---------------------------------------------------------------------------
@@ -99,9 +104,10 @@ export async function addRoadmapEntry(cwd, args) {
     throw new Error(`feature-writer: invalid status "${status}"`);
   }
 
-  const featuresDir = loadFeaturesDir(cwd);
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const existing = readFeature(cwd, args.code, featuresDir);
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+
+    const existing = await provider.getFeature(args.code);
     if (existing) {
       throw new Error(`feature-writer: feature "${args.code}" already exists`);
     }
@@ -118,14 +124,18 @@ export async function addRoadmapEntry(cwd, args) {
     if (args.complexity) feature.complexity = args.complexity;
     feature.position = args.position !== undefined
       ? args.position
-      : nextPositionInPhase(cwd, args.phase, featuresDir);
+      : await nextPositionInPhase(provider, args.phase);
     if (args.parent) feature.parent = args.parent;
     if (args.tags && args.tags.length) feature.tags = args.tags;
 
-    writeFeature(cwd, feature, featuresDir);
+    // Use createFeature (not putFeature) for the initial write of a brand-new
+    // feature: the not-found check above has already confirmed it doesn't exist,
+    // and createFeature carries the correct semantics for remote providers
+    // (e.g. GitHubProvider creates a new issue rather than patching an existing one).
+    await provider.createFeature(args.code, feature);
     let roadmapPath;
     try {
-      roadmapPath = writeRoadmap(cwd, { featuresDir });
+      roadmapPath = await provider.renderRoadmap();
     } catch (err) {
       throw partialWriteError(
         `add_roadmap_entry: feature.json for "${args.code}" was written but ROADMAP.md regeneration failed. ` +
@@ -134,7 +144,7 @@ export async function addRoadmapEntry(cwd, args) {
       );
     }
 
-    safeAppendEvent(cwd, {
+    await safeAppendEvent(cwd, {
       tool: 'add_roadmap_entry',
       code: args.code,
       to: status,
@@ -153,8 +163,9 @@ export async function addRoadmapEntry(cwd, args) {
 
 // Default position for a new feature: max existing position in the same
 // phase, plus 1. Falls back to 1 when the phase is empty.
-function nextPositionInPhase(cwd, phase, featuresDir) {
-  const peers = _listFeatures(cwd, featuresDir).filter(f => f.phase === phase);
+async function nextPositionInPhase(provider, phase) {
+  const all = await provider.listFeatures();
+  const peers = all.filter(f => f.phase === phase);
   if (peers.length === 0) return 1;
   const maxPos = peers.reduce((m, f) => {
     const p = typeof f.position === 'number' ? f.position : 0;
@@ -178,9 +189,14 @@ function partialWriteError(message, cause) {
 // Audit-log writes are best-effort: a failed append must NOT roll back a
 // committed mutation (per design Decision 2 and docs/mcp.md). Log a warning
 // and continue.
-function safeAppendEvent(cwd, event) {
+//
+// Routes through provider.appendEvent so GitHubProvider can post
+// <!--compose-event--> comments + mirror Projects v2. LocalFileProvider
+// delegates to feature-events.js#appendEvent producing byte-identical output.
+async function safeAppendEvent(cwd, event) {
   try {
-    appendEvent(cwd, event);
+    const provider = await getProvider(cwd);
+    await provider.appendEvent(event.code, event);
   } catch (err) {
     // eslint-disable-next-line no-console
     console.warn(`[feature-writer] audit append failed for ${event.tool} ${event.code ?? ''}: ${err.message}`);
@@ -207,9 +223,10 @@ export async function setFeatureStatus(cwd, args) {
     throw new Error(`feature-writer: invalid status "${args.status}" — must be one of ${[...STATUSES].join(', ')}`);
   }
 
-  const featuresDir = loadFeaturesDir(cwd);
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const feature = readFeature(cwd, args.code, featuresDir);
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+
+    const feature = await provider.getFeature(args.code);
     if (!feature) {
       throw new Error(`feature-writer: feature "${args.code}" not found`);
     }
@@ -230,11 +247,14 @@ export async function setFeatureStatus(cwd, args) {
       );
     }
 
-    const updates = { status: to };
-    if (args.commit_sha) updates.commit_sha = args.commit_sha;
-    updateFeature(cwd, args.code, updates, featuresDir);
+    // Build the updated feature object. We use persistFeatureRaw (not putFeature)
+    // because putFeature rejects status deltas by contract. Transition policy
+    // enforcement has already happened above — this is the raw persistence step.
+    const updated = { ...feature, status: to };
+    if (args.commit_sha) updated.commit_sha = args.commit_sha;
+    await provider.persistFeatureRaw(args.code, updated);
     try {
-      writeRoadmap(cwd, { featuresDir });
+      await provider.renderRoadmap();
     } catch (err) {
       throw partialWriteError(
         `set_feature_status: feature.json for "${args.code}" was updated (${from} → ${to}) but ROADMAP.md regeneration failed. ` +
@@ -253,7 +273,7 @@ export async function setFeatureStatus(cwd, args) {
     if (args.reason) event.reason = args.reason;
     if (args.commit_sha) event.commit_sha = args.commit_sha;
     if (args.force && !allowed.includes(to)) event.forced = true;
-    safeAppendEvent(cwd, event);
+    await safeAppendEvent(cwd, event);
 
     return { code: args.code, from, to, ts: new Date().toISOString() };
   });
@@ -382,8 +402,10 @@ export async function linkArtifact(cwd, args) {
   const featuresDir = loadFeaturesDir(cwd);
   rejectCanonicalArtifact(featuresDir, args.feature_code, normalizedPath);
 
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const feature = readFeature(cwd, args.feature_code, featuresDir);
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+
+    const feature = await provider.getFeature(args.feature_code);
     if (!feature) {
       throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
     }
@@ -408,9 +430,9 @@ export async function linkArtifact(cwd, args) {
     if (matchIdx !== -1) artifacts[matchIdx] = entry;
     else artifacts.push(entry);
 
-    updateFeature(cwd, args.feature_code, { artifacts }, featuresDir);
+    await provider.putFeature(args.feature_code, { ...feature, artifacts });
 
-    safeAppendEvent(cwd, {
+    await safeAppendEvent(cwd, {
       tool: 'link_artifact',
       code: args.feature_code,
       artifact_type: args.artifact_type,
@@ -452,9 +474,10 @@ export async function linkFeatures(cwd, args) {
     );
   }
 
-  const featuresDir = loadFeaturesDir(cwd);
-  return maybeIdempotent({ ...args, cwd }, () => {
-    const feature = readFeature(cwd, args.from_code, featuresDir);
+  return maybeIdempotent({ ...args, cwd }, async () => {
+    const provider = await getProvider(cwd);
+
+    const feature = await provider.getFeature(args.from_code);
     if (!feature) {
       throw new Error(`feature-writer: feature "${args.from_code}" not found`);
     }
@@ -474,9 +497,9 @@ export async function linkFeatures(cwd, args) {
     if (matchIdx !== -1) links[matchIdx] = entry;
     else links.push(entry);
 
-    updateFeature(cwd, args.from_code, { links }, featuresDir);
+    await provider.putFeature(args.from_code, { ...feature, links });
 
-    safeAppendEvent(cwd, {
+    await safeAppendEvent(cwd, {
       tool: 'link_features',
       code: args.from_code,
       to_code: args.to_code,
@@ -508,8 +531,8 @@ export async function linkFeatures(cwd, args) {
  */
 export async function getFeatureArtifacts(cwd, args) {
   validateCode(args.feature_code);
-  const featuresDir = loadFeaturesDir(cwd);
-  const feature = readFeature(cwd, args.feature_code, featuresDir);
+  const provider = await getProvider(cwd);
+  const feature = await provider.getFeature(args.feature_code);
   if (!feature) {
     throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
   }
@@ -525,6 +548,7 @@ export async function getFeatureArtifacts(cwd, args) {
   let canonical = null;
   try {
     const { ArtifactManager } = await import('../server/artifact-manager.js');
+    const featuresDir = loadFeaturesDir(cwd);
     const featureRoot = resolve(realCwd, featuresDir);
     if (existsSync(featureRoot)) {
       const manager = new ArtifactManager(featureRoot);
@@ -550,7 +574,7 @@ export async function getFeatureArtifacts(cwd, args) {
  * @param {'outgoing'|'incoming'|'both'} [args.direction='both']
  * @param {string} [args.kind]
  */
-export function getFeatureLinks(cwd, args) {
+export async function getFeatureLinks(cwd, args) {
   validateCode(args.feature_code);
   const direction = args.direction ?? 'both';
   if (!['outgoing', 'incoming', 'both'].includes(direction)) {
@@ -560,11 +584,11 @@ export function getFeatureLinks(cwd, args) {
   }
   const kind = args.kind;
 
-  const featuresDir = loadFeaturesDir(cwd);
+  const provider = await getProvider(cwd);
   const out = { feature_code: args.feature_code };
 
   if (direction === 'outgoing' || direction === 'both') {
-    const feature = readFeature(cwd, args.feature_code, featuresDir);
+    const feature = await provider.getFeature(args.feature_code);
     if (!feature) {
       throw new Error(`feature-writer: feature "${args.feature_code}" not found`);
     }
@@ -574,7 +598,7 @@ export function getFeatureLinks(cwd, args) {
   }
 
   if (direction === 'incoming' || direction === 'both') {
-    const all = _listFeatures(cwd, featuresDir);
+    const all = await provider.listFeatures();
     const incoming = [];
     for (const f of all) {
       if (f.code === args.feature_code) continue;

package/lib/roadmap-gen.js

@@ -46,22 +46,23 @@ function phaseStatus(features) {
 }
 
 /**
- * Generate ROADMAP.md content from feature.json files.
+ * Pure transform: merge a features array into a base ROADMAP.md text string
+ * and return the resulting text. No filesystem access.
  *
- * @param {string} cwd - Project root
+ * @param {string} baseText - The existing ROADMAP.md content (empty string for a fresh file)
+ * @param {Array} features - Feature objects (as returned by listFeatures)
  * @param {object} [opts]
- * @param {string} [opts.featuresDir] - Relative path to features dir
- * @param {string} [opts.projectName] - Project name for header
- * @param {string} [opts.projectDescription] - Project description for header
- * @returns {string} - Generated ROADMAP.md content
+ * @param {string} [opts.projectName] - Project name for default preamble
+ * @param {string} [opts.projectDescription] - Project description for default preamble
+ * @param {string} [opts.cwd] - Used only for drift emission (optional; defaults to '')
+ * @param {string} [opts.featuresDir] - Passed through to buildKeyDocs (optional)
+ * @returns {string} - Merged ROADMAP.md content
  */
-export function generateRoadmap(cwd, opts = {}) {
-  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
-  const features = listFeatures(cwd, featuresDir);
+export function generateRoadmapFromBase(baseText, features, opts = {}) {
+  const cwd = opts.cwd ?? '';
+  const featuresDir = opts.featuresDir ?? 'docs/features';
 
-  // Read existing ROADMAP.md once: preamble + curated content for splice-back.
-  const roadmapPath = join(cwd, 'ROADMAP.md');
-  const existingText = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
+  const existingText = baseText ?? '';
   const preamble = readPreamble(cwd, opts, existingText);
   const overrides = readPhaseOverrides(existingText);
   const anonRows = readAnonymousRows(existingText);
@@ -141,7 +142,7 @@ export function generateRoadmap(cwd, opts = {}) {
     if (override) {
       const overrideToken = parseStatusToken(override);
       if (overrideToken && overrideToken !== rollupStatus) {
-        emitDrift(cwd, { phaseId: phase, override, computed: rollupStatus });
+        if (cwd) emitDrift(cwd, { phaseId: phase, override, computed: rollupStatus });
       }
       // Override always wins. We can't reliably distinguish curated overrides
       // from previously-auto-generated rollups without explicit marking, so
@@ -189,6 +190,27 @@ export function generateRoadmap(cwd, opts = {}) {
   return sections.join('\n\n---\n\n') + '\n';
 }
 
+/**
+ * Generate ROADMAP.md content from feature.json files.
+ *
+ * @param {string} cwd - Project root
+ * @param {object} [opts]
+ * @param {string} [opts.featuresDir] - Relative path to features dir
+ * @param {string} [opts.projectName] - Project name for header
+ * @param {string} [opts.projectDescription] - Project description for header
+ * @returns {string} - Generated ROADMAP.md content
+ */
+export function generateRoadmap(cwd, opts = {}) {
+  const featuresDir = opts.featuresDir ?? loadFeaturesDir(cwd);
+  const features = listFeatures(cwd, featuresDir);
+
+  // Read existing ROADMAP.md once: preamble + curated content for splice-back.
+  const roadmapPath = join(cwd, 'ROADMAP.md');
+  const existingText = existsSync(roadmapPath) ? readFileSync(roadmapPath, 'utf-8') : '';
+
+  return generateRoadmapFromBase(existingText, features, { ...opts, cwd, featuresDir });
+}
+
 /**
  * Read the preamble (everything before the first ## Phase/Feature section)
  * from an existing ROADMAP.md, or generate a default one.
@@ -206,7 +228,12 @@ function readPreamble(cwd, opts, existingText) {
         if (firstHeadingIdx === -1 || idx < firstHeadingIdx) firstHeadingIdx = idx;
       }
     }
-    if (firstHeadingIdx > 0) {
+    if (firstHeadingIdx === -1) {
+      // No phase headings found — the entire file is a preamble (e.g. remote file
+      // contains only a header/intro with no generated sections yet). Preserve it.
+      const stripped = existingText.trimEnd().replace(/\n---\s*$/, '').trimEnd();
+      if (stripped.length > 0) return stripped;
+    } else if (firstHeadingIdx > 0) {
       // Walk back over a possible `---\n\n` separator immediately before the heading
       // so it doesn't get duplicated against the join("\n\n---\n\n") below.
       let cutIdx = firstHeadingIdx;

package/lib/tracker/cli.js

@@ -0,0 +1,31 @@
+import { providerFor } from './factory.js';
+
+export async function runTrackerCli(cwd, argv) {
+  const sub = argv[0];
+
+  // Guard unknown/missing subcommand BEFORE touching providerFor (no I/O on bad input).
+  if (sub !== 'status' && sub !== 'sync') {
+    return { output: 'usage: compose tracker <status|sync>', exitCode: 1 };
+  }
+
+  const provider = await providerFor(cwd);
+
+  if (sub === 'status') {
+    const h = await provider.health();
+    const output = [
+      `tracker provider: ${h.provider}`,
+      `canonical: ${h.canonical}`,
+      `pendingOps: ${h.pendingOps}`,
+      `conflicts: ${h.conflicts}`,
+      `mixedSources: ${(h.mixedSources || []).join(', ') || '(none)'}`,
+    ].join('\n');
+    return { output, exitCode: 0 };
+  }
+
+  // sub === 'sync'
+  const r = await provider.sync();
+  return {
+    output: `sync: drained ${r.drained}, quarantined ${r.quarantined ?? 0}, pending ${r.pending ?? 0}`,
+    exitCode: 0,
+  };
+}

package/lib/tracker/factory.js

@@ -0,0 +1,93 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { LocalFileProvider } from './local-provider.js';
+import { TrackerConfigError } from './provider.js';
+
+function loadTrackerConfig(cwd) {
+  const p = join(cwd, '.compose/compose.json');
+  // Absent file → local default (valid, not misconfig).
+  if (!existsSync(p)) return { provider: 'local' };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(p, 'utf8'));
+  } catch (e) {
+    // File EXISTS but JSON is malformed → fail fast (never silently fall back;
+    // silent fallback would mask misconfig — design.md Error Handling).
+    throw new TrackerConfigError(
+      `compose: tracker config at ${p} contains invalid JSON — ${e.message}`
+    );
+  }
+  // Absent tracker key → local default (valid).
+  const tracker = parsed.tracker;
+  if (tracker === undefined || tracker === null) return { provider: 'local' };
+  // tracker key present but structurally invalid → fail fast.
+  if (typeof tracker !== 'object' || Array.isArray(tracker)) {
+    throw new TrackerConfigError(
+      `compose: tracker config at ${p} has a "tracker" key but it is not an object (got ${Array.isArray(tracker) ? 'array' : typeof tracker})`
+    );
+  }
+  return tracker;
+}
+
+const ENTITY_METHODS = {
+  JOURNAL: ['readJournal', 'writeJournalEntry'],
+  VISION: ['getVisionState', 'putVisionState'],
+};
+
+function withFallback(active, local) {
+  const caps = active.capabilities();
+  return new Proxy(active, {
+    get(target, prop, receiver) {
+      if (typeof prop !== 'string') return Reflect.get(target, prop, receiver);
+      for (const [cap, methods] of Object.entries(ENTITY_METHODS)) {
+        if (methods.includes(prop) && !caps.has(cap)) {
+          const fn = local[prop];
+          return typeof fn === 'function' ? fn.bind(local) : fn;
+        }
+      }
+      const v = target[prop];
+      return typeof v === 'function' ? v.bind(target) : v;
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Test transport injection (TEST-ONLY — no production effect)
+// ---------------------------------------------------------------------------
+//
+// Tests that drive PRODUCTION entry points (writers) through a GitHub-configured
+// project need to inject a fixture transport WITHOUT modifying the on-disk config
+// (which can't hold a function). Call `setTestTransport(transport)` before
+// constructing the provider; call `clearTestTransport()` in afterEach.
+//
+// Production behavior: `_testTransport` is undefined by default → no effect.
+//
+let _testTransport = undefined;
+
+/**
+ * @param {object|null} transport - fixture transport for tests; null to clear.
+ */
+export function setTestTransport(transport) {
+  _testTransport = transport ?? undefined;
+}
+
+export function clearTestTransport() {
+  _testTransport = undefined;
+}
+
+export async function providerFor(cwd) {
+  const cfg = loadTrackerConfig(cwd);
+  const local = await new LocalFileProvider().init(cwd, {});
+  if (!cfg.provider || cfg.provider === 'local') return local;
+  if (cfg.provider === 'github') {
+    const { GitHubProvider } = await import('./github-provider.js');
+    // Merge in the test-only transport if one has been set via setTestTransport().
+    // In production _testTransport is undefined and cfg.github is passed as-is.
+    const ghCfg = _testTransport !== undefined
+      ? { ...(cfg.github ?? {}), _transport: _testTransport }
+      : (cfg.github ?? {});
+    const gh = await new GitHubProvider().init(cwd, ghCfg);
+    return withFallback(gh, local);
+  }
+  throw new TrackerConfigError(`unknown tracker provider "${cfg.provider}"`);
+}

package/lib/tracker/github-api.js

@@ -0,0 +1,115 @@
+import { execFileSync } from 'child_process';
+import { TrackerConfigError } from './provider.js';
+
+function resolveToken(auth = {}, noGhFallback = false) {
+  if (auth.token) return auth.token;
+  if (auth.tokenEnv && process.env[auth.tokenEnv]) return process.env[auth.tokenEnv];
+  if (noGhFallback) return null;
+  try { return execFileSync('gh', ['auth', 'token'], { encoding: 'utf8' }).trim() || null; }
+  catch { return null; }
+}
+
+export class GitHubApi {
+  constructor(cfg, transport = null) {
+    this.repo = cfg.repo;
+    if (!this.repo || !/^[^/]+\/[^/]+$/.test(this.repo)) {
+      throw new TrackerConfigError(`tracker.github.repo must be "owner/name" (got "${this.repo}")`);
+    }
+    this.token = resolveToken(cfg.auth, cfg.auth?._noGhFallback || cfg._noGhFallback);
+    if (!this.token) {
+      throw new TrackerConfigError('no GitHub token: set tracker.github.auth.tokenEnv or run `gh auth login`',
+        { missing: 'token' });
+    }
+    this.transport = transport;
+  }
+  async _req(method, path, body) {
+    if (this.transport) return this.transport.request(method, path, body);
+    const res = await fetch(`https://api.github.com${path}`, {
+      method, headers: { Authorization: `Bearer ${this.token}`, Accept: 'application/vnd.github+json' },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const remainingHdr = res.headers.get('x-ratelimit-remaining');
+    const resetHdr = res.headers.get('x-ratelimit-reset');
+    if (res.status === 403 && remainingHdr !== null && Number(remainingHdr) === 0) {
+      const e = new Error('rate limited');
+      e.rateLimit = { resetMs: Number(resetHdr) * 1000 - Date.now() };
+      throw e;
+    }
+    return { status: res.status, body: await res.json().catch(() => ({})), headers: res.headers };
+  }
+  async createIssue({ title, body, labels }) {
+    const r = await this._req('POST', `/repos/${this.repo}/issues`, { title, body, labels });
+    return r.body;
+  }
+  async getIssue(number) { return (await this._req('GET', `/repos/${this.repo}/issues/${number}`)).body; }
+  async updateIssue(number, patch) { return (await this._req('PATCH', `/repos/${this.repo}/issues/${number}`, patch)).body; }
+  async searchFeatureIssues() {
+    return (await this._req('GET', `/search/issues?q=repo:${this.repo}+label:compose-feature`)).body.items ?? [];
+  }
+  async addIssueComment(number, body) {
+    return (await this._req('POST', `/repos/${this.repo}/issues/${number}/comments`, { body })).body;
+  }
+  async listIssueComments(number) {
+    return (await this._req('GET', `/repos/${this.repo}/issues/${number}/comments`)).body ?? [];
+  }
+  async graphql(query, variables) {
+    const r = await this._req('POST', '/graphql', { query, variables });
+    return { data: r.body?.data, errors: r.body?.errors };
+  }
+
+  /**
+   * GET /repos/:repo — lightweight probe to verify token has repo access.
+   * Returns { status, body }; does NOT throw on 4xx.
+   */
+  async getRepo() {
+    return this._req('GET', `/repos/${this.repo}`);
+  }
+
+  /**
+   * GET /repos/:repo/contents/:path?ref=:ref
+   * Returns { text, sha } where text is the decoded file content.
+   * If the file does not exist (404), returns { text: '', sha: null }.
+   */
+  async getContents(path, ref) {
+    const query = ref ? `?ref=${encodeURIComponent(ref)}` : '';
+    const r = await this._req('GET', `/repos/${this.repo}/contents/${path}${query}`);
+    if (r.status === 404) return { text: '', sha: null };
+    if (r.status !== 200) {
+      throw new Error(
+        `getContents ${path}@${ref}: HTTP ${r.status} ${JSON.stringify(r.body)?.slice(0, 200)}`
+      );
+    }
+    const content = r.body?.content ?? '';
+    // GitHub returns base64 with embedded newlines — strip them before decoding.
+    const text = Buffer.from(content.replace(/\n/g, ''), 'base64').toString('utf-8');
+    const sha = r.body?.sha ?? null;
+    return { text, sha };
+  }
+
+  /**
+   * PUT /repos/:repo/contents/:path
+   * Creates or updates a file.
+   * @param {string} path - File path in the repo
+   * @param {string} text - New file content (UTF-8)
+   * @param {{ sha: string|null, branch: string, message: string }} opts
+   *   sha: current blob SHA (omit or pass null to create a new file)
+   *   branch: target branch
+   *   message: commit message
+   * On 409 (SHA conflict / optimistic-lock failure) throws with e.shaConflict = true.
+   */
+  async putContents(path, text, { sha, branch, message }) {
+    const body = {
+      message,
+      content: Buffer.from(text, 'utf-8').toString('base64'),
+      branch,
+    };
+    if (sha) body.sha = sha;
+    const r = await this._req('PUT', `/repos/${this.repo}/contents/${path}`, body);
+    if (r.status === 409) {
+      const e = new Error(`putContents: SHA conflict for ${path}`);
+      e.shaConflict = true;
+      throw e;
+    }
+    return r.body;
+  }
+}