@hobocode/thought-layer 0.6.1 → 0.8.5

package/README.md

@@ -19,14 +19,16 @@ This is open source and BYOK by design. The point is to help people build real t
 - **thought-layer-naming.** Name the thing, with rationale and domain-ready slugs.
 - **thought-layer-build.** Build the hardened PRD into a static-first, deploy-ready artifact, verified to run, and leave a manifest the deploy step reads. When a requirement genuinely needs a server, it also emits a real backend (serverless functions, a `schema.sql`, a names-only `.env.example`, and a `BACKEND.md` guide), with Neon Postgres as the documented default.
 - **thought-layer-deploy.** Take the build live to a URL you own, with no lock-in: a Netlify token deploys into your own account, or the Netlify CLI handles a logged-in or anonymous deploy.
+- **thought-layer-wiki.** Auto-generate a private Notion wiki, an internal intranet that organizes everything the workflow built (the thinking, the brand and styles, the business model, the PRD, the deploy rules) and links every artifact you delivered to GitHub. Private to your own Notion workspace, BYOK token, no public exposure.
+- **thought-layer-compliance.** Once the business is defined, research its governance, regulatory, compliance, licensing, and taxation-prep needs for your exact jurisdiction and entity type, and hand back a cited report (live links, costs, renewal cycles, filing deadlines, a critical path to launch) to review with your own legal and tax advisors. Research and a starting checklist, not legal or tax advice; it saves as the governance artifact, so it rides along into the GitHub bundle and the Notion wiki.
 - **thought-layer-speedrun.** A fast, unranked path to a build-ready spec when you do not need the full panel and score.
 - **Optional deep-dives**, pulled in when you want to go further than the backbone: `thought-layer-strategy`, `thought-layer-brand`, `thought-layer-market-research`, and `thought-layer-business-model`.
 
 **A Pi package** that adds, on top of the skills:
 
-- **Deterministic tools** the agent can call so the math is exact and never re-derived: `tl_score` (confidence to status and grade), `tl_domains` (availability, BYOK), `tl_project` (the numeric business projection), `tl_state` (the portable progress file), `tl_scaffold` (a deterministic, deployable static site from the spec + brand), and `deploy` (take the build live to a URL you own).
-- **Slash commands** (prompt templates): `/tl` runs the whole flow; `/tl-speedrun` is the fast unranked path; `/tl-panel`, `/tl-grill`, `/tl-prd`, `/tl-naming` run each stage; `/tl-build` builds the hardened PRD into a deploy-ready artifact; `/tl-deploy` takes it live.
-- **A `tl` CLI** for any shell agent (`npx -y @hobocode/thought-layer tl ...`): `read`/`list`/`answer`/`feedback`/`artifact`/`cursor`/`export` for the shared progress file, `scaffold` for the deployable static-site floor, and `deploy` to take the build live.
+- **Deterministic tools** the agent can call so the math is exact and never re-derived: `tl_score` (confidence to status and grade), `tl_domains` (availability, BYOK), `tl_project` (the numeric business projection), `tl_state` (the portable progress file), `tl_scaffold` (a deterministic, deployable static site from the spec + brand), `deploy` (take the build live to a URL you own), `tl_sync` (store and sync your sessions in your own private GitHub repo), `tl_artifacts` (deliver the full asset bundle to that repo), and `tl_wiki` (build a private Notion wiki from the session and those artifacts).
+- **Slash commands** (prompt templates): `/tl` runs the whole flow; `/tl-speedrun` is the fast unranked path; `/tl-panel`, `/tl-grill`, `/tl-prd`, `/tl-naming` run each stage; `/tl-build` builds the hardened PRD into a deploy-ready artifact; `/tl-deploy` takes it live; `/tl-artifacts` delivers the full asset bundle to your repo; `/tl-wiki` builds a private Notion intranet from it; `/tl-compliance` researches your GRC, licensing, and tax readiness.
+- **A `tl` CLI** for any shell agent (`npx -y @hobocode/thought-layer tl ...`): `read`/`list`/`answer`/`feedback`/`artifact`/`cursor`/`export` for the shared progress file, `scaffold` for the deployable static-site floor, `deploy` to take the build live, and `sync` to store and version your sessions in your own private GitHub repo.
 
 ## Install
 
@@ -71,6 +73,8 @@ The hosted version of the rigor lives at [weareallproductmanagersnow.com](https:
 - **Phase 4 (done):** a `deploy` step (`/tl-deploy`, the `deploy` tool, or `tl deploy`) that takes the build live to a URL you own, closing the loop. With a Netlify token it deploys into your own account via the file-digest API (owned immediately, no claim step); with no token it delegates to your Netlify CLI - logged in it creates a site in your account, logged out it deploys anonymously with a one-hour claim link. BYOK, no central account, no lock-in. `--dry-run` shows the plan first.
 - **Backend-capable build (done):** when the three-question backend test shows a product genuinely needs a server, `/tl-build` emits a real backend alongside the static front end (serverless functions per backend requirement, a `schema.sql`, a names-only `.env.example`, an updated `netlify.toml`, and a `BACKEND.md` guide), with Neon Postgres as the documented default and overridable to any Postgres. Static stays the default, gated by the same backend test.
 - **Backend deploy (done):** when `build.json` declares a backend, `/tl-deploy` (the `deploy` tool, or `tl deploy`) ships it automatically alongside the front end: the functions go up via your Netlify CLI and the declared env var names are set on the site (values read only from your environment, BYOK). `DATABASE_URL` is bring-your-own by default; `--provision-db` (your own Neon key) and `--apply-schema` (psql) are opt in, and `--static-only` ships just the front end. Owned, no lock-in.
+- **Artifacts and wiki (done):** `tl artifacts` (the `tl_artifacts` tool) delivers the full asset bundle for a session, the PRD, brand guide + look book + logo, SWOT and business-model infographics, market research, a landing page, and any build/deploy provenance, to your own private sessions repo under `artifacts/<session>/`. `tl wiki` (the `tl_wiki` tool) then builds a **private Notion wiki**, an internal intranet that organizes all of it into a page per workflow area plus an Artifacts database that links each file. Notion pages are private to your own workspace (auth, not public); the integration token is BYOK from the environment. Free for one user, upgradeable for a team.
+- **Sessions and collaboration (done):** `tl sync` (and the `tl_sync` tool) stores your session files in your OWN private GitHub repo. Save any number of named sessions (one private repo for your own projects, a separate repo per founder you collaborate with), list and open them, and sync. Git carries history and multi-user; the kit reconciles concurrent edits itself (newest wins per field, conflicts reported), so it never hand-merges JSON. Collaboration is granted on GitHub (you add collaborators, the kit never changes permissions). BYOK, no central account.
 
 ## Notes for contributors
 

package/core/artifacts-io.ts

@@ -0,0 +1,146 @@
+// Node IO for artifact delivery, shared by the `tl artifacts` CLI and the
+// tl_artifacts Pi tool. The pure generation lives in artifacts.ts; this loads a
+// session's state, builds the artifact bundle, copies any on-disk build/deploy
+// provenance, writes it all under artifacts/<slug>/ in the user's own private
+// sessions repo, and commits + pushes via the same git plumbing as sync-io.ts.
+//
+// Artifacts are generated and overwrite-wins: they are not field-merged like the
+// session JSON, and pullAndReconcile already takes the remote copy of any
+// non-session file, so this composes cleanly with sync.
+//
+// Secrets: nothing here reads a token. git uses its credential helper; no token
+// is ever placed on argv or persisted.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { git, isGitRepo, loadConfig, resolveWorkspace } from "./sync-io.ts";
+import { slugify } from "./sync.ts";
+import { STATE_DIR, loadStateFile } from "./state-file.ts";
+import { buildArtifactSet, type ArtifactFile, type ArtifactKind } from "./artifacts.ts";
+import type { StateOpResult } from "./state-ops.ts";
+
+export interface ArtifactsRunOptions {
+  path?: string; // explicit source state file (else the session in the clone)
+  name?: string; // session name (the artifacts subfolder slug)
+  workspace?: string; // select an existing sessions workspace by label
+  dir?: string; // explicit clone dir
+  message?: string; // commit message
+  noPush?: boolean; // commit only, do not push
+  noDeliver?: boolean; // write the bundle into the clone but do not commit/push
+  domain?: string; // landing-page domain
+  founderName?: string; // landing-page founder
+}
+
+const ok = (message: string, details: Record<string, unknown> = {}): StateOpResult => ({ ok: true, message, details });
+const fail = (message: string, details: Record<string, unknown> = {}): StateOpResult => ({ ok: false, message, details });
+
+// On-disk build/deploy provenance, looked for relative to the source state file.
+// build.json/deploy.json and the .md provenance sit in the .thought-layer/ dir;
+// schema.sql/netlify.toml/BACKEND.md sit at the project root beside it.
+const STATE_DIR_ARTIFACTS = ["build.json", "deploy.json", "TRACEABILITY.md", "DECISIONS.md"];
+const ROOT_ARTIFACTS = ["BACKEND.md", "schema.sql", "netlify.toml", ".env.example"];
+
+const kindOf = (path: string): ArtifactKind =>
+  path.endsWith(".md") ? "markdown" : path.endsWith(".svg") ? "svg" : path.endsWith(".html") ? "html" : path.endsWith(".json") ? "json" : "text";
+
+// Parse "owner/name", "https://github.com/owner/name(.git)", or "git@github.com:owner/name"
+// into "owner/name". Returns null when it is a local path or unrecognizable.
+export function repoOwnerName(repo: string): string | null {
+  const m = String(repo || "").trim().match(/(?:github\.com[:/])?([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+  if (!m) return null;
+  if (m[1] === "." || m[1] === "..") return null;
+  return `${m[1]}/${m[2]}`;
+}
+
+export function runArtifacts(opts: ArtifactsRunOptions, ctx: { generatedAt: string }): StateOpResult {
+  try {
+    const cfg = loadConfig();
+    const { cloneDir, ws } = resolveWorkspace(opts as never, cfg);
+    if (!isGitRepo(cloneDir)) {
+      return fail(`No sessions workspace at ${cloneDir}. Run tl sync init --repo <owner/name> first, then save a session.`, { cloneDir });
+    }
+
+    const slug = slugify(opts.name || ws?.activeSession?.replace(/\.json$/, "") || "");
+    if (!slug) return fail("Name the session whose artifacts to deliver: tl artifacts --name <name>.");
+
+    // Source state precedence mirrors sync save: an explicit --path or
+    // THOUGHT_LAYER_STATE wins; otherwise the session file in the clone.
+    const sessionPath = join(cloneDir, STATE_DIR, `${slug}.json`);
+    const useExplicit = !!((opts.path && opts.path.trim()) || (process.env["THOUGHT_LAYER_STATE"] || "").trim());
+    const loadTarget = useExplicit ? opts.path : existsSync(sessionPath) ? sessionPath : opts.path;
+    const loaded = loadStateFile(loadTarget);
+    if (!loaded.exists) {
+      return fail(`No session "${slug}" found (looked at ${loaded.path}). Save it first with tl sync save --name ${slug}.`, { cloneDir });
+    }
+
+    const { files, manifest } = buildArtifactSet(loaded.state, {
+      generatedAt: ctx.generatedAt,
+      domain: opts.domain,
+      founderName: opts.founderName,
+    });
+
+    // Copy any on-disk build/deploy provenance beside the source state file into
+    // a Deploy/ subfolder, extending the manifest with each one.
+    const srcStateDir = dirname(loaded.path);
+    const srcRoot = basename(srcStateDir) === STATE_DIR ? dirname(srcStateDir) : srcStateDir;
+    const extra: ArtifactFile[] = [];
+    const copyIfPresent = (fromDir: string, fname: string): void => {
+      const from = join(fromDir, fname);
+      if (!existsSync(from)) return;
+      try {
+        const content = readFileSync(from, "utf8");
+        const rel = `Deploy/${fname}`;
+        files[rel] = content;
+        extra.push({ path: rel, bytes: Buffer.byteLength(content, "utf8"), kind: kindOf(rel), source: "build/deploy" });
+      } catch { /* skip unreadable provenance */ }
+    };
+    STATE_DIR_ARTIFACTS.forEach((f) => copyIfPresent(srcStateDir, f));
+    ROOT_ARTIFACTS.forEach((f) => copyIfPresent(srcRoot, f));
+    manifest.files = [...manifest.files, ...extra].sort((a, b) => a.path.localeCompare(b.path));
+
+    // Write the bundle under artifacts/<slug>/ in the clone, plus the manifest.
+    const baseRel = join("artifacts", slug);
+    const baseAbs = join(cloneDir, baseRel);
+    for (const [rel, content] of Object.entries(files)) {
+      const dest = join(baseAbs, rel);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, content);
+    }
+    writeFileSync(join(baseAbs, "artifacts.json"), JSON.stringify(manifest, null, 2) + "\n");
+
+    const fileCount = Object.keys(files).length + 1; // + artifacts.json
+    if (opts.noDeliver) {
+      return ok(`Generated ${fileCount} artifact file(s) into ${baseAbs} (local only; not committed).`,
+        { cloneDir, dir: baseAbs, session: slug, files: Object.keys(files), count: fileCount, committed: false, pushed: false });
+    }
+
+    // Force-add past the sessions .gitignore (which ignores dist/, build.json,
+    // etc.): the delivered artifacts under artifacts/ are intentionally tracked.
+    git(cloneDir, ["add", "-f", "--", baseRel]);
+    const msg = opts.message || `Deliver artifacts for ${slug}`;
+    const committed = git(cloneDir, ["commit", "-m", msg]).status === 0;
+    let pushed = false;
+    let pushNote = "";
+    if (committed && !opts.noPush) {
+      const p = git(cloneDir, ["push"]);
+      pushed = p.status === 0;
+      if (!pushed) pushNote = ` Could not push (${(p.err || "").split("\n")[0] || "see git output"}); commit is local, run tl sync push when ready.`;
+    }
+
+    // Derive clickable GitHub URLs for the wiki to link to.
+    const branch = git(cloneDir, ["rev-parse", "--abbrev-ref", "HEAD"]).out.trim() || ws?.defaultBranch || "main";
+    const ownerName = repoOwnerName(ws?.repo || "");
+    const githubBase = ownerName ? `https://github.com/${ownerName}/blob/${branch}/${baseRel}` : null;
+    const urls: Record<string, string> = {};
+    if (githubBase) for (const rel of Object.keys(files)) urls[rel] = `${githubBase}/${rel.split("/").map(encodeURIComponent).join("/")}`;
+
+    return ok(
+      `Delivered ${fileCount} artifact file(s) for "${slug}" to ${baseRel} in ${cloneDir}.` +
+        `${committed ? (opts.noPush ? " Committed locally (no push)." : pushed ? " Committed and pushed." : pushNote) : " Nothing changed since the last delivery."}` +
+        `${githubBase ? `\nView on GitHub: ${githubBase}` : ""}`,
+      { cloneDir, dir: baseRel, session: slug, files: Object.keys(files), count: fileCount, committed, pushed, branch, repo: ownerName, githubBase, urls },
+    );
+  } catch (e) {
+    return fail(`tl_artifacts error: ${(e as Error).message}`);
+  }
+}