@logicseek/hello-cc 0.1.2 → 0.1.4

package/lib/guidance.mjs

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function guidanceMarkdown() {
+  return `# hello-cc Coordination Rules
+
+This project may be edited by multiple Claude Code and Codex CLI sessions.
+
+Use \`hcc\` as the source of truth for cross-session coordination. If the user
+asks what other sessions are doing, do not answer from generic model knowledge.
+Run the project-local commands below and summarize the result.
+
+Each terminal session must use a stable peer id, for example codex-a,
+codex-b, claude-a, claude-b, or gpu-runner-a.
+
+Status checks:
+- \`hcc peers\` shows known Claude/Codex/shell sessions.
+- \`hcc task list\` shows all open tasks. Tasks stay visible until \`done\` or
+  \`abandoned\`; they are not read/unread items.
+- \`hcc msg inbox\` shows unread messages for this session.
+- \`hcc lock list\` shows active advisory locks.
+- \`hcc status\` summarizes peers, tasks, locks, inbox, and recent events.
+- \`hcc team status --task N\` summarizes explicit subtasks for a parent task.
+
+Read-only work:
+- Reading files, searching, inspecting \`git diff\` / \`git status\`, reviewing
+  uncommitted changes, and running non-mutating checks such as \`node --check\`
+  do not require locks.
+- For read-only review, do not acquire file locks. If another live peer already
+  holds write locks on changed files, report that the review is only a current
+  snapshot and not a final commit-ready verdict.
+- Use tasks, messages, events, or handoffs to make read-only review visible;
+  do not use advisory locks to reserve files you are only reading.
+
+Review and monitoring:
+- Reviewing another peer's work is a read-only activity. You may inspect current
+  diffs, task state, messages, handoffs, and non-mutating checks while that peer
+  keeps its write locks.
+- If you find a concrete issue in another peer's task, proactively send that
+  peer an \`hcc msg\` with the task id, affected file or behavior, why it is a
+  problem, and a suggested fix or verification step.
+- Continue monitoring until the peer fixes the issue, records a follow-up task,
+  or hands off. Do not silently treat a snapshot review as final approval.
+
+Before mutating work:
+- Register with hcc.
+- Read current status with \`hcc status\`, \`hcc state\`, \`hcc task list\`, and \`hcc msg inbox\`.
+- If \`hcc state\` shows a current task for this peer, continue that task until
+  handoff, done, or blocked instead of claiming a new task.
+- Claim one task before editing or mutating shared state when this peer has no
+  current task.
+- If work needs multiple peers, use \`hcc team plan\` and \`hcc team start\`
+  explicitly; do not create or claim hidden extra tasks.
+
+Before editing or mutating shared resources:
+- Acquire an advisory lock for the file, directory, module, or shared resource.
+- If another live peer holds the lock, message that peer instead of editing.
+- Acquire locks only before writes or shared-resource mutation, including file
+  edits, formatting, staging/committing through \`.git/index\`, intentional DB
+  data/schema changes, starting/stopping/restarting shared runtimes, or taking
+  over tmux/session/port resources.
+- Commit-readiness checks are read-only until staging begins. Do not lock source
+  files for review. Before committing, ensure no live peer holds write locks on
+  the files to be committed, then lock \`.git/index\` only while staging and
+  committing.
+
+During work:
+- Keep changes scoped to the claimed task.
+- Send progress messages when another session needs context.
+
+Before stopping:
+- Mark the task done or blocked.
+- Create a handoff with changed files, tests, and remaining risks.
+- Release locks you no longer need.
+`;
+}
+
+export function writeGuidance(root) {
+  const guidePath = path.join(root, '.hello-cc', 'HCC.md');
+  fs.mkdirSync(path.dirname(guidePath), { recursive: true });
+  const content = guidanceMarkdown();
+  fs.writeFileSync(guidePath, content);
+  const clause = `\n<!-- hello-cc:start -->\n\n${content}\n<!-- hello-cc:end -->\n`;
+  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
+    const target = path.join(root, file);
+    if (!fs.existsSync(target)) {
+      fs.writeFileSync(target, clause.trimStart());
+      continue;
+    }
+    const existing = fs.readFileSync(target, 'utf8');
+    const updated = existing.includes('<!-- hello-cc:start -->')
+      ? existing.replace(/<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->/, clause.trim())
+      : `${existing.trimEnd()}\n${clause}`;
+    fs.writeFileSync(target, updated);
+  }
+  return guidePath;
+}
+
+export function removeGuidanceBlocks(root) {
+  const changed = [];
+  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
+    const target = path.join(root, file);
+    if (!fs.existsSync(target)) continue;
+    const existing = fs.readFileSync(target, 'utf8');
+    const updated = existing
+      .replace(/\n?<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->\n?/g, '\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trimEnd();
+    if (updated !== existing) {
+      fs.writeFileSync(target, updated ? `${updated}\n` : '');
+      changed.push(target);
+    }
+  }
+  return changed;
+}

package/lib/package-meta.mjs

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function packageRoot(fromUrl = import.meta.url) {
+  return path.resolve(fileURLToPath(fromUrl), '..', '..');
+}
+
+export function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function readPackageJson(root) {
+  return readJson(path.join(root, 'package.json'));
+}
+
+export function readPackageMeta(root) {
+  const pkg = readPackageJson(root);
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    packageJson: pkg
+  };
+}

package/lib/release-notes.mjs

@@ -0,0 +1,40 @@
+export function normalizeVersion(version) {
+  return String(version || '').replace(/^v/, '');
+}
+
+export function releaseSection(markdown, version) {
+  const lines = markdown.split(/\r?\n/);
+  const heading = `## ${version}`;
+  const start = lines.findIndex((line) => line.trim() === heading);
+  if (start < 0) return null;
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').trimEnd();
+}
+
+export function validateReleaseSection(section, version) {
+  const problems = [];
+  if (!section) {
+    problems.push(`CHANGELOG.md is missing section ## ${version}`);
+    return problems;
+  }
+  if (!section.includes('### Summary')) problems.push(`## ${version} is missing ### Summary`);
+  if (!section.includes('### Highlights')) problems.push(`## ${version} is missing ### Highlights`);
+  if (section.includes('TODO') || section.includes('TBD')) problems.push(`## ${version} still contains TODO/TBD text`);
+  const bulletCount = (section.match(/^- /gm) || []).length;
+  if (bulletCount < 2) problems.push(`## ${version} should include at least two release-note bullets`);
+  return problems;
+}
+
+export function repoFromPackage(pkg) {
+  const repo = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+  if (!repo) return null;
+  const match = repo.match(/github\.com[:/](.+?\/.+?)(?:\.git)?$/);
+  return match ? match[1] : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicseek/hello-cc",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Local control plane for coordinating Claude Code, Codex, and other coding CLI sessions.",
   "type": "module",
   "bin": {
@@ -24,6 +24,8 @@
   "scripts": {
     "release:notes": "node ./scripts/release-notes.mjs",
     "release:check": "node ./scripts/release-notes.mjs --check",
+    "release:github": "node ./scripts/github-release.mjs",
+    "release:github:dry-run": "node ./scripts/github-release.mjs --dry-run",
     "smoke": "node ./bin/hcc.mjs --help",
     "test": "node ./scripts/regression.mjs",
     "test:regression": "node ./scripts/regression.mjs"

package/scripts/github-release.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { packageRoot, readPackageJson } from '../lib/package-meta.mjs';
+import {
+  normalizeVersion,
+  releaseSection,
+  repoFromPackage,
+  validateReleaseSection
+} from '../lib/release-notes.mjs';
+
+const repoRoot = packageRoot(import.meta.url);
+const githubApi = 'https://api.github.com';
+
+function usage() {
+  console.log(`github-release
+
+Usage:
+  node scripts/github-release.mjs [--version VERSION] [--repo OWNER/REPO] [--dry-run]
+
+Creates or updates the GitHub Release for vVERSION using the matching
+CHANGELOG.md section as the release body.
+
+Authentication:
+  Set GH_TOKEN or GITHUB_TOKEN to a token with repo release permissions.
+`);
+}
+
+function parseArgs(argv) {
+  const opts = { dryRun: false, help: false, repo: null, version: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+    } else if (arg === '--dry-run') {
+      opts.dryRun = true;
+    } else if (arg === '--repo') {
+      opts.repo = argv[++i];
+      if (opts.repo === undefined) throw new Error('Missing value for --repo');
+    } else if (arg.startsWith('--repo=')) {
+      opts.repo = arg.slice('--repo='.length);
+    } else if (arg === '--version') {
+      opts.version = argv[++i];
+      if (opts.version === undefined) throw new Error('Missing value for --version');
+    } else if (arg.startsWith('--version=')) {
+      opts.version = arg.slice('--version='.length);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return opts;
+}
+
+function envToken() {
+  return process.env.GH_TOKEN || process.env.GITHUB_TOKEN || '';
+}
+
+async function githubRequest(method, route, token, body = null) {
+  const response = await fetch(`${githubApi}${route}`, {
+    method,
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      'User-Agent': 'hello-cc-release-script'
+    },
+    body: body ? JSON.stringify(body) : undefined
+  });
+  const text = await response.text();
+  const data = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const detail = data?.message ? `: ${data.message}` : '';
+    const error = new Error(`GitHub API ${method} ${route} failed with ${response.status}${detail}`);
+    error.status = response.status;
+    throw error;
+  }
+  return data;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    usage();
+    return;
+  }
+
+  const pkg = readPackageJson(repoRoot);
+  const version = normalizeVersion(opts.version || pkg.version);
+  const tag = `v${version}`;
+  const repo = opts.repo || process.env.GITHUB_REPOSITORY || repoFromPackage(pkg);
+  if (!repo) throw new Error('Missing repository; pass --repo OWNER/REPO');
+
+  const changelog = fs.readFileSync(path.join(repoRoot, 'CHANGELOG.md'), 'utf8');
+  const body = releaseSection(changelog, version);
+  const problems = validateReleaseSection(body, version);
+  if (problems.length) {
+    console.error(problems.join('\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const payload = {
+    tag_name: tag,
+    name: tag,
+    body,
+    draft: false,
+    prerelease: false
+  };
+
+  if (opts.dryRun) {
+    console.log(JSON.stringify({
+      ok: true,
+      dry_run: true,
+      repo,
+      tag,
+      name: payload.name,
+      body_length: body.length,
+      body_preview: body.split(/\r?\n/).slice(0, 8).join('\n')
+    }, null, 2));
+    return;
+  }
+
+  const token = envToken();
+  if (!token) throw new Error('Missing GH_TOKEN or GITHUB_TOKEN');
+
+  let existing = null;
+  try {
+    existing = await githubRequest('GET', `/repos/${repo}/releases/tags/${tag}`, token);
+  } catch (err) {
+    if (err.status !== 404) throw err;
+  }
+
+  const result = existing
+    ? await githubRequest('PATCH', `/repos/${repo}/releases/${existing.id}`, token, payload)
+    : await githubRequest('POST', `/repos/${repo}/releases`, token, payload);
+
+  console.log(JSON.stringify({
+    ok: true,
+    action: existing ? 'updated' : 'created',
+    repo,
+    tag,
+    url: result.html_url,
+    body_length: body.length
+  }, null, 2));
+}
+
+main().catch((err) => {
+  console.error(err.message || String(err));
+  process.exitCode = 1;
+});