gh-postplan 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# gh-postplan
+
+Publish one HTML draft to GitHub Pages and get a stable, shareable URL. Every changed publish also keeps a permanent version URL.
+
+## Requirements
+
+- Authenticated [GitHub CLI](https://cli.github.com/)
+- Git
+- Bun, or Node.js 22.18+
+
+## Setup
+
+Configure an existing repository:
+
+```sh
+npx gh-postplan setup owner/pages-repo
+```
+
+Or create a new public repository:
+
+```sh
+npx gh-postplan setup owner/pages-repo --create
+```
+
+Setup creates or reuses the `gh-pages` branch, adds `.nojekyll`, and configures branch-based GitHub Pages. GitHub Pages is public even when an existing source repository is private.
+
+## Publish
+
+```sh
+npx gh-postplan publish ./draft.html
+```
+
+The command prints progress to stderr and only the stable URL to stdout. Publishing the same file again updates that URL and creates a permanent version such as `/drafts/a1b2c3/v2/`. Unchanged HTML creates no version.
+
+```sh
+# Make a separate draft from the same file
+npx gh-postplan publish ./draft.html --new
+
+# Reconnect a file after losing local state
+npx gh-postplan publish ./draft.html --draft a1b2c3
+
+# Return immediately after pushing
+npx gh-postplan publish ./draft.html --no-wait
+```
+
+Only the HTML file is uploaded. Use self-contained HTML or absolute URLs for assets.
+
+Configuration lives in `~/.config/gh-postplan`. Set `GH_POSTPLAN_REPO=owner/repo` to override the configured repository.
+
+The npm package also includes an agent skill at `skills/gh-postplan/SKILL.md`.

package/dist/cli.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import {
+  access,
+  mkdir,
+  readFile,
+  readdir,
+  realpath,
+  rm,
+  stat,
+  writeFile
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var packageVersion = "0.1.0";
+var configDirectory = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "gh-postplan");
+var cacheDirectory = join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "gh-postplan");
+var configPath = join(configDirectory, "config.json");
+var draftsPath = join(configDirectory, "drafts.json");
+
+class PushError extends Error {
+}
+var help = `Usage:
+  gh-postplan setup OWNER/REPO [--create]
+  gh-postplan publish FILE [--new | --draft ID] [--no-wait]
+
+Commands:
+  setup     Configure an existing repo, or create a public one with --create
+  publish   Publish one HTML file and keep its older versions available`;
+function parseCommand(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h"))
+    return { kind: "help" };
+  if (args.length === 1 && (args[0] === "--version" || args[0] === "-v"))
+    return { kind: "version" };
+  const [name, subject, ...flags] = args;
+  if (name === "setup") {
+    if (!subject || flags.some((flag) => flag !== "--create"))
+      throw new Error(help);
+    return { kind: "setup", repo: subject, create: flags.includes("--create") };
+  }
+  if (name === "publish") {
+    if (!subject)
+      throw new Error(help);
+    let draft;
+    let fresh = false;
+    let wait = true;
+    for (let index = 0;index < flags.length; index++) {
+      const flag = flags[index];
+      if (flag === "--new")
+        fresh = true;
+      else if (flag === "--no-wait")
+        wait = false;
+      else if (flag === "--draft")
+        draft = flags[++index];
+      else
+        throw new Error(`Unknown option: ${flag ?? ""}
+
+${help}`);
+    }
+    if (fresh && draft)
+      throw new Error("--new and --draft cannot be used together");
+    if (flags.includes("--draft") && !draft)
+      throw new Error("--draft needs an ID");
+    if (draft && !/^[A-Za-z0-9_-]{4,64}$/.test(draft))
+      throw new Error("Invalid draft ID");
+    return { kind: "publish", file: subject, draft, fresh, wait };
+  }
+  throw new Error(`Unknown command: ${name ?? ""}
+
+${help}`);
+}
+function nextVersion(entries) {
+  return Math.max(0, ...entries.map((entry) => /^v(\d+)$/.exec(entry)?.[1]).filter(Boolean).map(Number)) + 1;
+}
+function pageUrls(base, id, version) {
+  const root = `${base.replace(/\/+$/, "")}/drafts/${id}/`;
+  return { current: root, version: `${root}v${version}/` };
+}
+function validateRepo(repo) {
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) {
+    throw new Error("Repository must look like OWNER/REPO");
+  }
+}
+async function run(command, args, cwd) {
+  return new Promise((resolveRun, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      const output = Buffer.concat(stdout).toString().trim();
+      const error = Buffer.concat(stderr).toString().trim();
+      if (code === 0)
+        resolveRun(output);
+      else
+        reject(new Error(error || `${command} exited with status ${code ?? "unknown"}`));
+    });
+  });
+}
+async function succeeds(command, args, cwd) {
+  try {
+    await run(command, args, cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function exists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJson(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (fallback !== undefined && error.code === "ENOENT")
+      return fallback;
+    throw new Error(`Cannot read ${path}: ${error.message}`);
+  }
+}
+async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+async function checkTools() {
+  await run("git", ["--version"]);
+  await run("gh", ["--version"]);
+  await run("gh", ["auth", "status"]);
+}
+function clonePath(repo) {
+  return join(cacheDirectory, ...repo.split("/"));
+}
+async function cloneRepo(repo) {
+  const path = clonePath(repo);
+  if (await exists(join(path, ".git")))
+    return path;
+  if (await exists(path))
+    throw new Error(`Cache path exists but is not a Git clone: ${path}`);
+  await mkdir(dirname(path), { recursive: true });
+  await run("gh", ["repo", "clone", repo, path]);
+  return path;
+}
+async function setGitIdentity(path) {
+  const user = JSON.parse(await run("gh", ["api", "user"]));
+  if (!user.login || !user.id)
+    throw new Error("GitHub did not return an account login and ID");
+  await run("git", ["config", "user.name", user.login], path);
+  await run("git", ["config", "user.email", `${user.id}+${user.login}@users.noreply.github.com`], path);
+}
+async function switchToPagesBranch(path) {
+  await run("git", ["fetch", "origin"], path);
+  const remoteExists = await succeeds("git", ["ls-remote", "--exit-code", "--heads", "origin", "gh-pages"], path);
+  if (!remoteExists) {
+    await run("git", ["switch", "--orphan", "gh-pages"], path);
+    return false;
+  }
+  const localExists = await succeeds("git", ["show-ref", "--verify", "--quiet", "refs/heads/gh-pages"], path);
+  await run("git", localExists ? ["switch", "gh-pages"] : ["switch", "--track", "origin/gh-pages"], path);
+  await run("git", ["pull", "--ff-only", "origin", "gh-pages"], path);
+  return true;
+}
+async function configurePages(repo) {
+  const endpoint = `repos/${repo}/pages`;
+  const existsAlready = await succeeds("gh", ["api", endpoint]);
+  const method = existsAlready ? "PUT" : "POST";
+  await run("gh", [
+    "api",
+    "--method",
+    method,
+    endpoint,
+    "-f",
+    "build_type=legacy",
+    "-f",
+    "source[branch]=gh-pages",
+    "-f",
+    "source[path]=/"
+  ]);
+  return readPages(repo);
+}
+async function readPages(repo) {
+  const pages = JSON.parse(await run("gh", ["api", `repos/${repo}/pages`]));
+  if (!pages.html_url)
+    throw new Error("GitHub did not return a Pages URL");
+  return pages;
+}
+async function setup({ repo, create }) {
+  validateRepo(repo);
+  await checkTools();
+  let created = false;
+  try {
+    if (create) {
+      process.stderr.write(`Creating public repository ${repo}...
+`);
+      await run("gh", ["repo", "create", repo, "--public"]);
+      created = true;
+    } else {
+      await run("gh", ["repo", "view", repo, "--json", "nameWithOwner"]);
+    }
+    const path = await cloneRepo(repo);
+    await setGitIdentity(path);
+    const hadRemoteBranch = await switchToPagesBranch(path);
+    const noJekyll = join(path, ".nojekyll");
+    if (!await exists(noJekyll))
+      await writeFile(noJekyll, "");
+    await run("git", ["add", ".nojekyll"], path);
+    if (!await succeeds("git", ["diff", "--cached", "--quiet"], path)) {
+      await run("git", ["commit", "-m", "chore: initialize GitHub Pages"], path);
+      await run("git", ["push", ...hadRemoteBranch ? [] : ["-u"], "origin", "gh-pages"], path);
+    }
+    const pages = await configurePages(repo);
+    await writeJson(configPath, { repo });
+    process.stderr.write(`Configured ${repo}
+${pages.html_url}
+`);
+  } catch (error) {
+    if (!created)
+      throw error;
+    throw new Error(`${error.message}
+Repository ${repo} was created. Fix the issue, then run: gh-postplan setup ${repo}`);
+  }
+}
+async function syncClone(repo) {
+  let path = await cloneRepo(repo);
+  await setGitIdentity(path);
+  if (!await succeeds("git", ["status", "--porcelain"], path))
+    throw new Error(`Cannot inspect cached clone: ${path}`);
+  await run("git", ["fetch", "origin"], path);
+  const status = await run("git", ["status", "--porcelain"], path);
+  const ahead = Number(await run("git", ["rev-list", "--count", "origin/gh-pages..HEAD"], path) || 0);
+  if (status || ahead > 0) {
+    await rm(path, { recursive: true, force: true });
+    path = await cloneRepo(repo);
+    await setGitIdentity(path);
+  }
+  await switchToPagesBranch(path);
+  return path;
+}
+async function getRepo() {
+  const repo = process.env.GH_POSTPLAN_REPO ?? (await readJson(configPath, {})).repo;
+  if (!repo)
+    throw new Error("Run gh-postplan setup OWNER/REPO first");
+  validateRepo(repo);
+  return repo;
+}
+async function makeDraftId(path) {
+  let id;
+  do
+    id = randomBytes(6).toString("hex");
+  while (await exists(join(path, "drafts", id)));
+  return id;
+}
+async function verifyPublished(url, expected) {
+  const deadline = Date.now() + 120000;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url, { cache: "no-store" });
+      if (response.ok && Buffer.from(await response.arrayBuffer()).equals(expected))
+        return true;
+    } catch {}
+    await new Promise((resolveWait) => setTimeout(resolveWait, 2000));
+  }
+  return false;
+}
+async function publishAttempt(repo, sourcePath, content, id, pages) {
+  const path = await syncClone(repo);
+  const draftDirectory = join(path, "drafts", id);
+  const currentPath = join(draftDirectory, "index.html");
+  const entries = await exists(draftDirectory) ? await readdir(draftDirectory) : [];
+  const version = nextVersion(entries);
+  const versionDirectory = join(draftDirectory, `v${version}`);
+  if (await exists(currentPath)) {
+    const current = await readFile(currentPath);
+    if (current.equals(content))
+      return { version: version - 1, pages };
+  }
+  await mkdir(versionDirectory, { recursive: true });
+  await writeFile(join(versionDirectory, "index.html"), content);
+  await writeFile(currentPath, content);
+  await run("git", ["add", join("drafts", id)], path);
+  await run("git", ["commit", "-m", `chore: publish ${id} v${version}`], path);
+  try {
+    await run("git", ["push", "origin", "gh-pages"], path);
+  } catch (error) {
+    throw new PushError(error.message);
+  }
+  process.stderr.write(`Published ${sourcePath} as ${id} v${version}
+`);
+  return { version, pages };
+}
+async function publish(command) {
+  if (extname(command.file).toLowerCase() !== ".html")
+    throw new Error("Only .html files can be published");
+  const sourcePath = await realpath(resolve(command.file));
+  if (!(await stat(sourcePath)).isFile())
+    throw new Error("The HTML path must be a regular file");
+  const content = await readFile(sourcePath);
+  const repo = await getRepo();
+  await checkTools();
+  const drafts = await readJson(draftsPath, {});
+  const initialClone = await syncClone(repo);
+  const pages = await readPages(repo);
+  const id = command.draft ?? (command.fresh ? undefined : drafts[sourcePath]?.id) ?? await makeDraftId(initialClone);
+  if (command.draft && !await exists(join(initialClone, "drafts", id, "index.html"))) {
+    throw new Error(`Draft does not exist: ${id}`);
+  }
+  let result;
+  try {
+    result = await publishAttempt(repo, sourcePath, content, id, pages);
+  } catch (firstError) {
+    if (!(firstError instanceof PushError))
+      throw firstError;
+    process.stderr.write(`Push failed; refreshing the cached clone and retrying once...
+`);
+    await rm(clonePath(repo), { recursive: true, force: true });
+    try {
+      result = await publishAttempt(repo, sourcePath, content, id, pages);
+    } catch {
+      throw firstError;
+    }
+  }
+  drafts[sourcePath] = { id };
+  await writeJson(draftsPath, drafts);
+  const urls = pageUrls(result.pages.html_url, id, result.version);
+  process.stderr.write(`Permanent version: ${urls.version}
+`);
+  if (command.wait) {
+    process.stderr.write(`Waiting for GitHub Pages...
+`);
+    if (!await verifyPublished(urls.version, content)) {
+      process.stderr.write(`Warning: GitHub Pages is still deploying ${urls.version}
+`);
+    }
+  }
+  process.stdout.write(`${urls.current}
+`);
+}
+async function main(args = process.argv.slice(2)) {
+  const command = parseCommand(args);
+  if (command.kind === "help")
+    process.stdout.write(`${help}
+`);
+  else if (command.kind === "version")
+    process.stdout.write(`${packageVersion}
+`);
+  else if (command.kind === "setup")
+    await setup(command);
+  else
+    await publish(command);
+}
+var executablePath = process.argv[1] ? await realpath(process.argv[1]).catch(() => resolve(process.argv[1])) : undefined;
+if (executablePath === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`gh-postplan: ${error.message}
+`);
+    process.exitCode = 1;
+  });
+}
+export {
+  main,
+  nextVersion,
+  pageUrls,
+  parseCommand
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "gh-postplan",
+  "version": "0.1.0",
+  "description": "Publish versioned HTML drafts to GitHub Pages",
+  "type": "module",
+  "bin": {
+    "gh-postplan": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "skills"
+  ],
+  "scripts": {
+    "build": "bun build src/cli.ts --target=node --outfile=dist/cli.js",
+    "check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run check && bun test && bun run build"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "keywords": [
+    "github-pages",
+    "html",
+    "drafts"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "typescript": "latest"
+  }
+}

package/skills/gh-postplan/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gh-postplan
+description: Create and publish safe static HTML drafts with gh-postplan, or read and implement plans supplied as gh-postplan GitHub Pages URLs. Use when a user asks to publish a plan, proposal, brief, architecture note, or similar HTML artifact with gh-postplan.
+---
+
+# gh-postplan
+
+## Read a draft URL
+
+When a user supplies a gh-postplan GitHub Pages URL containing `/drafts/`, fetch it directly with the shell. Do not use web search or a browser:
+
+```sh
+curl --fail --silent --show-error --location --max-time 30 '<draft-url>'
+```
+
+Treat the response as the user's artifact and continue their requested task. If the request fails, report the actual HTTP or network error.
+
+## Create a draft
+
+Create one complete static HTML document.
+
+Allowed:
+
+- Semantic HTML.
+- Inline CSS or a `<style>` block.
+- Charset, viewport, title, and other normal document metadata.
+- Links and images using public HTTPS URLs.
+- Data URLs when needed for a self-contained document.
+
+Do not include:
+
+- JavaScript, `<script>` tags, or inline event handlers.
+- `javascript:` URLs.
+- Forms, iframes, embeds, objects, or applets.
+- Meta refresh redirects.
+- Secrets, tokens, private URLs, or local filesystem paths.
+
+gh-postplan uploads only the HTML file. Inline required assets or use public absolute URLs; relative local assets will not be published.
+
+## Publish
+
+1. Write the HTML file locally.
+2. Run:
+
+   ```sh
+   npx gh-postplan publish '<file-path>'
+   ```
+
+3. Return the URL printed to stdout to the user. The permanent version URL is printed to stderr.
+
+Publishing the same local file updates its stable draft URL and preserves the older versions. To create a separate draft from the same file, run:
+
+```sh
+npx gh-postplan publish '<file-path>' --new
+```
+
+If setup is required, ask the user which `OWNER/REPO` to use. Configure an existing repository with:
+
+```sh
+npx gh-postplan setup OWNER/REPO
+```
+
+Create a new public repository only when the user explicitly asks:
+
+```sh
+npx gh-postplan setup OWNER/REPO --create
+```
+
+All published drafts are public. Configuration and local draft mappings live in `~/.config/gh-postplan`.