#!/usr/bin/env node // handoff-path.mjs: where the handoff document goes, and whether git would pick it up. // // The handoff skill names its file /-handoff.md, takes the // timestamp from the clock rather than a guess, creates the folder, and checks // whether the file would be tracked by git (is this a repo, is the path // ignored). That is a fixed sequence with one right answer per machine, so it // lives here. Whether to add an ignore line is the user's call. import fs from "node:fs"; import os from "node:os"; import path from "node:path"; import { execFileSync } from "node:child_process"; import { EXIT, fail, out, parseArgs, run, isoDate, now } from "./common.mjs"; const USAGE = ` handoff-path.mjs: pick the handoff file path and check it against git. JSON on stdout. node handoff-path.mjs [--dir temp|] [--root ] [--dry-run] --dir temp (the default): the OS temporary directory. Anything else is a folder, relative to --root (default: the current directory), e.g. handoffs (a project folder literally named temp: ./temp). Created if missing (not with --dry-run). Prints { path, dir, created, timestamp, git: { repo, inRepo, ignored, ignoreLine }, warning? }. The file name is -handoff.md; if one already exists for this minute, -2, -3... is appended so earlier handoffs are never overwritten. git.ignored is null when the file is outside a repo (nothing to ignore); false means it would show up in git status, and then git.ignoreLine is the .gitignore line to offer and the top-level warning says so. Exit: 0 ok · 2 bad arguments · 5 the folder cannot be created, or --dir names an existing file (not-a-folder). `; function git(cwd, args) { try { return { ok: true, out: execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim() }; } catch (err) { return { ok: false, status: err.status }; } } run(USAGE, async (argv) => { const args = parseArgs(argv, { booleans: ["dry-run"], values: ["dir", "root"] }); const root = path.resolve(args.root || "."); const choice = args.dir || "temp"; const dir = choice === "temp" ? os.tmpdir() : path.resolve(root, choice); let created = false; if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) { fail(EXIT.REFUSED, "not-a-folder", `${dir} exists and is a file, not a folder.`, "Pass a folder for --dir (a new one is created), or use --dir temp."); } if (!fs.existsSync(dir)) { if (!args["dry-run"]) { try { fs.mkdirSync(dir, { recursive: true }); created = true; } catch (err) { fail(EXIT.REFUSED, "mkdir-failed", `Could not create ${dir}: ${err.message}`, "Pick another folder, or use --dir temp."); } } } const d = now(); const pad = (n) => String(n).padStart(2, "0"); const timestamp = `${isoDate(d)}-${pad(d.getHours())}${pad(d.getMinutes())}`; let file = path.join(dir, `${timestamp}-handoff.md`); for (let n = 2; fs.existsSync(file); n++) file = path.join(dir, `${timestamp}-${n}-handoff.md`); // Compare real paths: git prints the repo's real top level, while the folder // may arrive as an 8.3 short name (C:\Users\JOHN~1\...) or through a symlink // (macOS /tmp -> /private/tmp). A folder not created yet (--dry-run) resolves // through its nearest existing ancestor. Git runs from that ancestor too, so // the file is checked against the repo it would actually land in. const existing = (() => { let p = dir; while (!fs.existsSync(p) && path.dirname(p) !== p) p = path.dirname(p); return p; })(); const realDir = path.join(fs.realpathSync.native(existing), path.relative(existing, dir)); const realFile = path.join(realDir, path.basename(file)); const top = git(existing, ["rev-parse", "--show-toplevel"]); const gitInfo = { repo: top.ok || git(root, ["rev-parse", "--show-toplevel"]).ok, inRepo: false, ignored: null }; if (top.ok) { const repoRoot = fs.realpathSync.native(path.resolve(top.out)); const relToRepo = path.relative(repoRoot, realFile); gitInfo.inRepo = !!relToRepo && !relToRepo.startsWith("..") && !path.isAbsolute(relToRepo); if (gitInfo.inRepo) { // check-ignore exits 0 when ignored, 1 when not; it honours global and nested ignore files. const ci = git(repoRoot, ["check-ignore", "-q", relToRepo.split(path.sep).join("/")]); gitInfo.ignored = ci.ok; const relDir = path.relative(repoRoot, realDir).split(path.sep).join("/"); // The repo root itself is never the line to ignore: offer the handoff files instead. gitInfo.ignoreLine = relDir ? `${relDir}/` : "*-handoff.md"; } } out({ ok: true, path: file, dir, created, dryRun: !!args["dry-run"], timestamp, git: gitInfo, ...(gitInfo.inRepo && gitInfo.ignored === false ? { warning: `This file would be tracked by git. Offer to add "${gitInfo.ignoreLine}" to .gitignore; do not add it without asking.` } : {}), }); });