@uplift-beyond/upgo 0.0.0-stage → 0.4.0

package/dist/src/core/ops.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { itemSchema, pointersSchema, sectionSchema, slug, STATUSES } from "./schema.js";
+import * as m from "./mutate.js";
+// The one write vocabulary the dashboard speaks. The server validates a request body against `opSchema`
+// and runs it through `applyOp`; the CLI calls the same mutate functions.
+const s = itemSchema.shape;
+const clearable = (t) => t.nullable().optional();
+export const itemInputSchema = itemSchema.omit({ id: true, status: true, created: true, updated: true }).extend({
+    id: slug.optional(),
+    status: z.enum(STATUSES).optional(),
+    // Undoing a delete keeps the original date.
+    created: s.created.optional(),
+});
+export const itemPatchSchema = z.strictObject({
+    section: s.section.optional(),
+    title: s.title.optional(),
+    phase: s.phase.optional(),
+    status: s.status.optional(),
+    body: clearable(z.string()),
+    size: clearable(s.size.unwrap()),
+    scope: clearable(s.scope.unwrap()),
+    pointers: clearable(pointersSchema),
+    detail: clearable(s.detail.unwrap()),
+    related: clearable(s.related.unwrap()),
+    note: clearable(z.string()),
+});
+const n = sectionSchema.shape.n;
+const title = sectionSchema.shape.title;
+export const opSchema = z.discriminatedUnion("op", [
+    z.strictObject({ op: z.literal("add"), item: itemInputSchema }),
+    z.strictObject({ op: z.literal("edit"), id: slug, patch: itemPatchSchema }),
+    z.strictObject({ op: z.literal("done"), id: slug, note: z.string().optional() }),
+    z.strictObject({ op: z.literal("drop"), id: slug, reason: z.string().trim().min(1) }),
+    z.strictObject({ op: z.literal("reopen"), id: slug }),
+    z.strictObject({ op: z.literal("delete"), id: slug }),
+    z.strictObject({ op: z.literal("move"), id: slug, section: n.optional(), before: slug.optional(), after: slug.optional() }),
+    z.strictObject({ op: z.literal("addSection"), title, n: n.optional() }),
+    z.strictObject({ op: z.literal("renameSection"), n, title }),
+    z.strictObject({ op: z.literal("moveSection"), n, before: n.nullable() }),
+    z.strictObject({ op: z.literal("deleteSection"), n }),
+]);
+export function applyOp(file, op, day) {
+    switch (op.op) {
+        case "add":
+            return m.addItem(file, op.item, day).file;
+        case "edit":
+            return m.editItem(file, op.id, op.patch, day);
+        case "done":
+            return m.setStatus(file, op.id, "done", op.note, day);
+        case "drop":
+            return m.setStatus(file, op.id, "dropped", op.reason, day);
+        case "reopen":
+            return m.setStatus(file, op.id, "planned", undefined, day);
+        case "delete":
+            return m.deleteItem(file, op.id);
+        case "move":
+            return m.moveItem(file, op.id, { section: op.section, before: op.before, after: op.after }, day);
+        case "addSection":
+            return m.addSection(file, op.title, op.n).file;
+        case "renameSection":
+            return m.renameSection(file, op.n, op.title);
+        case "moveSection":
+            return m.moveSection(file, op.n, op.before);
+        case "deleteSection":
+            return m.deleteSection(file, op.n);
+        default:
+            throw new Error(`unknown op ${JSON.stringify(op)}`);
+    }
+}

package/dist/src/core/registry.js

@@ -0,0 +1,92 @@
+import { constants, copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { formatIssues, slug } from "./schema.js";
+import { withLock, writeAtomic } from "./store.js";
+import { UpgoError } from "./util.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+// Package root: src/core in the repo, dist/src/core when built.
+export const UPGO_DIR = resolve(HERE, existsSync(resolve(HERE, "../../package.json")) ? "../.." : "../../..");
+const entrySchema = z.strictObject({ id: slug, path: z.string().min(1) });
+const registrySchema = z.array(entrySchema);
+const DATA_DIR = join(homedir(), ".upgo");
+let ready = false;
+// Tests point this at a temp file so they never touch the real registry.
+export function registryPath() {
+    if (process.env.UPGO_REGISTRY)
+        return process.env.UPGO_REGISTRY;
+    const path = join(DATA_DIR, "registry.json");
+    if (!ready) {
+        ready = true;
+        mkdirSync(DATA_DIR, { recursive: true });
+        // Older versions kept it in the install folder, which an npm update wipes.
+        const legacy = join(UPGO_DIR, "registry.json");
+        try {
+            // EXCL: a parallel first run may already have written the new one.
+            if (!existsSync(path) && existsSync(legacy))
+                copyFileSync(legacy, path, constants.COPYFILE_EXCL);
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+    }
+    return path;
+}
+const samePath = (a, b) => process.platform === "win32" ? resolve(a).toLowerCase() === resolve(b).toLowerCase() : resolve(a) === resolve(b);
+export function readRegistry() {
+    const path = registryPath();
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new UpgoError(`registry ${path} is not valid JSON: ${e.message}`);
+    }
+    const parsed = registrySchema.safeParse(raw);
+    if (!parsed.success)
+        throw new UpgoError(`registry ${path} is invalid:`, formatIssues(parsed.error));
+    return parsed.data;
+}
+async function writeRegistry(entries) {
+    await writeAtomic(registryPath(), JSON.stringify(entries, null, 2) + "\n");
+}
+export function findEntry(id) {
+    return readRegistry().find((e) => e.id === id);
+}
+export function findEntryByPath(path) {
+    return readRegistry().find((e) => samePath(e.path, path));
+}
+// Throws if `id` at `path` clashes with another registration; returns the entry when it is this one already.
+export function checkRegistrable(id, path, entries = readRegistry()) {
+    const byId = entries.find((e) => e.id === id);
+    if (byId && !samePath(byId.path, path))
+        throw new UpgoError(`project id \`${id}\` is already registered for ${byId.path}`);
+    const byPath = entries.find((e) => samePath(e.path, path));
+    if (byPath && byPath.id !== id)
+        throw new UpgoError(`${path} is already registered as \`${byPath.id}\``);
+    return byId;
+}
+export async function register(id, path) {
+    return withLock(registryPath(), async () => {
+        const entries = readRegistry();
+        const byId = checkRegistrable(id, path, entries);
+        if (byId)
+            return byId;
+        const entry = { id, path: resolve(path) };
+        await writeRegistry([...entries, entry]);
+        return entry;
+    });
+}
+export async function forget(id) {
+    await withLock(registryPath(), async () => {
+        const entries = readRegistry();
+        if (!entries.some((e) => e.id === id))
+            throw new UpgoError(`no registered project \`${id}\``);
+        await writeRegistry(entries.filter((e) => e.id !== id));
+    });
+}

package/dist/src/core/render.js

@@ -0,0 +1,40 @@
+import { isOpen, PHASE_LABEL } from "./schema.js";
+const COLLAPSED = ["wayLater", "maybe"];
+export const GENERATED_MARK = "<!-- Generated by upgo from goals.json. Never edit this file or goals.json by hand: use the upgo CLI. -->";
+const indent = (s) => s.trim().replace(/\r?\n/g, "\n  ");
+function itemLine(item) {
+    const tags = [PHASE_LABEL[item.phase], item.status === "partial" ? "partial" : ""].filter(Boolean).join(", ");
+    return `- \`${item.id}\` ${item.title} (${tags})`;
+}
+// goals.json -> the slim goals.md agents auto-load. Open items only, one line each.
+export function render(file) {
+    const open = file.items.filter(isOpen);
+    const live = file.sections.filter((s) => open.some((i) => i.section === s.n));
+    const closed = file.sections.filter((s) => !live.includes(s));
+    const out = [`# ${file.project}: goals`, "", GENERATED_MARK, ""];
+    // LF only: `upgo check` compares against goals.md read back with CRLF normalized.
+    if (file.purpose?.trim())
+        out.push(file.purpose.trim().replace(/\r\n?/g, "\n"), "");
+    out.push("Open work only. Full item: `upgo show <id>`. Any slice: `upgo list --phase later,wayLater,maybe`, `--status done,dropped`, `--section <n>`, `--search <text>`.", "");
+    if (closed.length)
+        out.push(`Closed sections: ${closed.map((s) => `§${s.n} ${s.title}`).join(" · ")}`, "");
+    if (file.traps.length) {
+        out.push("## Traps", "");
+        for (const t of file.traps)
+            out.push(`- **${t.title}**${t.body?.trim() ? ` ${indent(t.body)}` : ""}`);
+        out.push("");
+    }
+    for (const s of live) {
+        out.push(`## ${s.n}. ${s.title}`, "");
+        const mine = open.filter((i) => i.section === s.n);
+        for (const item of mine.filter((i) => !COLLAPSED.includes(i.phase)))
+            out.push(itemLine(item));
+        const counts = COLLAPSED.map((p) => [p, mine.filter((i) => i.phase === p).length]).filter(([, c]) => c > 0);
+        if (counts.length) {
+            const what = counts.map(([p, c]) => `${c} ${PHASE_LABEL[p]}`).join(", ");
+            out.push(`- Plus ${what}: \`upgo list --section ${s.n} --phase ${counts.map(([p]) => p).join(",")}\``);
+        }
+        out.push("");
+    }
+    return out.join("\n").replace(/\n+$/, "\n");
+}

package/dist/src/core/rules.js

@@ -0,0 +1,35 @@
+export const EM_DASH = "\u2014";
+function dupes(values) {
+    const seen = new Set();
+    return [...new Set(values.filter((v) => seen.size === seen.add(v).size))];
+}
+// Rules a single file must satisfy on its own; every save runs them.
+export function localIssues(file) {
+    const issues = [];
+    for (const id of dupes(file.items.map((i) => i.id)))
+        issues.push(`duplicate item id \`${id}\``);
+    for (const id of dupes(file.traps.map((t) => t.id)))
+        issues.push(`duplicate trap id \`${id}\``);
+    for (const n of dupes(file.sections.map((s) => s.n)))
+        issues.push(`duplicate section number ${n}`);
+    const sections = new Set(file.sections.map((s) => s.n));
+    for (const item of file.items) {
+        if (!sections.has(item.section))
+            issues.push(`item \`${item.id}\` is in section ${item.section}, which does not exist`);
+        if (item.status === "dropped" && !item.note?.trim())
+            issues.push(`dropped item \`${item.id}\` needs a reason in \`note\``);
+        for (const ref of item.related ?? []) {
+            if (ref === `${file.project}:${item.id}`)
+                issues.push(`item \`${item.id}\` relates to itself`);
+        }
+    }
+    const where = [
+        ...file.items.filter((i) => JSON.stringify(i).includes(EM_DASH)).map((i) => `item \`${i.id}\``),
+        ...file.traps.filter((t) => JSON.stringify(t).includes(EM_DASH)).map((t) => `trap \`${t.id}\``),
+        ...file.sections.filter((s) => s.title.includes(EM_DASH)).map((s) => `section ${s.n}`),
+        ...(file.purpose?.includes(EM_DASH) ? ["purpose"] : []),
+    ];
+    for (const w of where)
+        issues.push(`${w} contains an em dash (U+2014); use a comma, colon or hyphen`);
+    return issues;
+}

package/dist/src/core/schema.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { PHASES, POINTER_KEYS, SIZES, STATUSES, isOpenStatus } from "./vocab.js";
+export * from "./vocab.js";
+export const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const DATE = /^\d{4}-\d{2}-\d{2}$/;
+export const slug = z.string().max(60).regex(SLUG, "must be a lowercase slug like `random-logouts`");
+const date = z.string().regex(DATE, "must be YYYY-MM-DD");
+const text = z.string().trim().min(1);
+const list = z.array(text).min(1);
+const line = (max) => text.max(max).regex(/^[^\r\n]*$/, "must be one line");
+// `projectId:itemId`, the only way one project points at another.
+export const ref = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:-[a-z0-9]+)*$/, "must be `projectId:itemId`");
+export const pointersSchema = z.strictObject(Object.fromEntries(POINTER_KEYS.map((k) => [k, list.optional()])));
+export const itemSchema = z.strictObject({
+    id: slug,
+    section: z.number().int().nonnegative(),
+    title: line(200),
+    body: z.string().optional(),
+    phase: z.enum(PHASES),
+    status: z.enum(STATUSES),
+    size: z.enum(SIZES).optional(),
+    scope: list.optional(),
+    pointers: pointersSchema.optional(),
+    detail: text.optional(),
+    related: z.array(ref).min(1).optional(),
+    created: date,
+    updated: date,
+    note: z.string().optional(),
+});
+export const sectionSchema = z.strictObject({
+    n: z.number().int().nonnegative(),
+    title: line(120),
+});
+export const trapSchema = z.strictObject({
+    id: slug,
+    title: line(200),
+    body: z.string().optional(),
+});
+// Ideas an agent left for the user, kept in suggestions.json beside goals.json.
+export const suggestionSchema = z.strictObject({
+    id: slug,
+    title: line(200),
+    body: z.string().optional(),
+    created: date,
+});
+export const suggestionsFileSchema = z.strictObject({
+    version: z.literal(1),
+    suggestions: z.array(suggestionSchema),
+});
+export const goalsFileSchema = z.strictObject({
+    $schema: z.string().optional(),
+    version: z.literal(1),
+    project: slug,
+    purpose: z.string().optional(),
+    sections: z.array(sectionSchema),
+    traps: z.array(trapSchema),
+    items: z.array(itemSchema),
+});
+export const isOpen = (item) => isOpenStatus(item.status);
+export const SCHEMA_URL = "https://raw.githubusercontent.com/JennyTheGem/upgo/main/goals.schema.json";
+// Also matches files written before the URL moved to GitHub.
+export const isManaged = (goalsJson) => /"\$schema"\s*:\s*"[^"]*\/upgo\/(?:main\/)?goals\.schema\.json"/.test(goalsJson);
+export function jsonSchema() {
+    return z.toJSONSchema(goalsFileSchema, { target: "draft-2020-12" });
+}
+export function formatIssues(error) {
+    return error.issues.map((i) => `${i.path.length ? i.path.join(".") : "(root)"}: ${i.message}`);
+}

package/dist/src/core/store.js

@@ -0,0 +1,122 @@
+import fsp from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { formatIssues, goalsFileSchema, SCHEMA_URL } from "./schema.js";
+import { localIssues } from "./rules.js";
+import { render } from "./render.js";
+import { UpgoError } from "./util.js";
+export const GOALS = "goals.json";
+export const MD = "goals.md";
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT_MS = 3_000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Nearest folder at or above `start` holding a goals.json.
+export function findProjectDir(start) {
+    for (let dir = resolve(start);; dir = dirname(dir)) {
+        if (existsSync(join(dir, GOALS)))
+            return dir;
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+export function parseGoals(raw) {
+    const parsed = goalsFileSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new UpgoError("goals.json does not match the schema:", formatIssues(parsed.error));
+    return parsed.data;
+}
+export function readGoals(dir) {
+    const path = join(dir, GOALS);
+    if (!existsSync(path))
+        throw new UpgoError(`no goals.json in ${dir} (run \`upgo init\` there first)`);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new UpgoError(`goals.json is not valid JSON: ${e.message}`);
+    }
+    return parseGoals(raw);
+}
+export function serialize(file) {
+    // Parsing again puts every key in schema order, so diffs stay stable whoever wrote the file.
+    const { $schema: _drop, ...rest } = parseGoals(file);
+    return JSON.stringify({ $schema: SCHEMA_URL, ...rest }, null, 2) + "\n";
+}
+// Write a temp file and rename it over the target, so a reader never sees half a file.
+export async function writeAtomic(path, content) {
+    const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await fsp.writeFile(tmp, content, "utf8");
+        for (let attempt = 0;; attempt++) {
+            try {
+                await fsp.rename(tmp, path);
+                return;
+            }
+            catch (e) {
+                // Windows refuses a rename while a watcher or editor briefly holds the target.
+                const code = e.code;
+                if (attempt >= 5 || (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES"))
+                    throw e;
+                await sleep(30);
+            }
+        }
+    }
+    catch (e) {
+        await fsp.rm(tmp, { force: true });
+        throw e;
+    }
+}
+// Exclusive lockfile next to `target`; a lock older than 10s is a crashed writer and gets taken over.
+export async function withLock(target, fn) {
+    const lock = `${target}.lock`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            const handle = await fsp.open(lock, "wx");
+            await handle.writeFile(`${process.pid} ${new Date().toISOString()}`);
+            await handle.close();
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            const stat = await fsp.stat(lock).catch(() => null);
+            if (stat && Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+                await fsp.rm(lock, { force: true });
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new UpgoError(`${target} is locked by another writer (${lock})`);
+            await sleep(50);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        // A throw here would report a finished write as failed; a leftover lock just goes stale.
+        await fsp.rm(lock, { force: true }).catch(() => { });
+    }
+}
+// Validates, then writes goals.json and the generated goals.md. Nothing is written if validation fails.
+export async function saveGoals(dir, file) {
+    const json = serialize(file);
+    const clean = parseGoals(JSON.parse(json));
+    const issues = localIssues(clean);
+    if (issues.length)
+        throw new UpgoError("refusing to save an invalid goals.json:", issues);
+    const md = render(clean);
+    await writeAtomic(join(dir, GOALS), json);
+    try {
+        await writeAtomic(join(dir, MD), md);
+    }
+    catch (e) {
+        // The change is in; a caller that retried it would apply it twice.
+        throw new UpgoError(`goals.json was saved, but ${MD} could not be written (${e.message}): run \`upgo render\``);
+    }
+    return clean;
+}
+export async function updateGoals(dir, mutate) {
+    return withLock(join(dir, GOALS), async () => saveGoals(dir, mutate(readGoals(dir))));
+}

package/dist/src/core/suggestions.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { EM_DASH } from "./rules.js";
+import { formatIssues, suggestionsFileSchema } from "./schema.js";
+import { withLock, writeAtomic } from "./store.js";
+import { slugify, uniqueSlug, UpgoError } from "./util.js";
+export const SUGGESTIONS = "suggestions.json";
+function parse(raw, problem = `${SUGGESTIONS} does not match the schema:`) {
+    const parsed = suggestionsFileSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new UpgoError(problem, formatIssues(parsed.error));
+    return parsed.data.suggestions;
+}
+// No file means no suggestions.
+export function readSuggestions(dir) {
+    const path = join(dir, SUGGESTIONS);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new UpgoError(`${SUGGESTIONS} is not valid JSON: ${e.message}`);
+    }
+    return parse(raw);
+}
+// For readers that carry on past a broken file: the list, or what is wrong with it.
+export function trySuggestions(dir) {
+    try {
+        return { suggestions: readSuggestions(dir) };
+    }
+    catch (e) {
+        if (!(e instanceof UpgoError))
+            throw e;
+        // One line: the message carries the details as a list too.
+        return { suggestions: [], suggestionsError: [e.message.split("\n")[0], e.details.join("; ")].filter(Boolean).join(" ") };
+    }
+}
+export async function updateSuggestions(dir, mutate) {
+    const path = join(dir, SUGGESTIONS);
+    return withLock(path, async () => {
+        // Bad input, not a broken file, so the agent does not go looking for one.
+        const list = parse({ version: 1, suggestions: mutate(readSuggestions(dir)) }, `refusing to save an invalid ${SUGGESTIONS}:`);
+        await writeAtomic(path, JSON.stringify({ version: 1, suggestions: list }, null, 2) + "\n");
+        return list;
+    });
+}
+export function addSuggestion(list, input, day) {
+    if (JSON.stringify(input).includes(EM_DASH))
+        throw new UpgoError("a suggestion contains an em dash (U+2014); use a comma, colon or hyphen");
+    const id = uniqueSlug(slugify(input.title), new Set(list.map((s) => s.id)));
+    return { list: [...list, { id, title: input.title, ...(input.body?.trim() ? { body: input.body } : {}), created: day }], id };
+}
+export function removeSuggestions(list, ids) {
+    const missing = ids.filter((id) => !list.some((s) => s.id === id));
+    if (missing.length)
+        throw new UpgoError(`no suggestion ${missing.map((id) => `\`${id}\``).join(", ")}`);
+    return list.filter((s) => !ids.includes(s.id));
+}

package/dist/src/core/summary.js

@@ -0,0 +1,27 @@
+import { PHASES, isOpenStatus } from "./vocab.js";
+// Done items per project the dashboard gets, newest first.
+export const RECENT = 5;
+// How much an item counts toward progress. Unsized counts as M.
+export const SIZE_WEIGHT = { S: 1, M: 2, L: 4 };
+// Done share of everything not dropped, weighted by size. Open maybes are not committed work, so they don't count.
+export function percentDone(items) {
+    const weigh = (pick) => items.filter(pick).reduce((n, i) => n + SIZE_WEIGHT[i.size ?? "M"], 0);
+    const done = weigh((i) => i.status === "done");
+    const total = done + weigh((i) => isOpenStatus(i.status) && i.phase !== "maybe");
+    return total ? Math.round((done / total) * 100) : 0;
+}
+// What the dashboard shows per project: counts, open items per phase, the open `now` and `next` items, the last
+// change and the latest done items. Zod-free for the web bundle.
+export function summarize(file) {
+    const open = file.items.filter((i) => isOpenStatus(i.status));
+    const count = (s) => file.items.filter((i) => i.status === s).length;
+    const phases = Object.fromEntries(PHASES.map((p) => [p, open.filter((i) => i.phase === p).length]));
+    const inPhase = (p) => open.filter((i) => i.phase === p).map(({ id, title, status, size }) => ({ id, title, status, size }));
+    const updated = file.items.reduce((d, i) => (i.updated > d ? i.updated : d), "") || undefined;
+    const recent = file.items
+        .filter((i) => i.status === "done")
+        .sort((a, b) => b.updated.localeCompare(a.updated))
+        .slice(0, RECENT)
+        .map(({ id, title, note, updated }) => ({ id, title, note, updated }));
+    return { purpose: file.purpose, open: open.length, done: count("done"), dropped: count("dropped"), percent: percentDone(file.items), phases, now: inPhase("now"), next: inPhase("next"), updated, recent };
+}

package/dist/src/core/util.js

@@ -0,0 +1,36 @@
+// Every failure a user or agent can cause is an UpgoError: the CLI prints its message, the server sends it as a 400.
+export class UpgoError extends Error {
+    details;
+    constructor(message, details = []) {
+        super(details.length ? `${message}\n${details.map((d) => `  - ${d}`).join("\n")}` : message);
+        this.name = "UpgoError";
+        this.details = details;
+    }
+}
+export function today(now = new Date()) {
+    const p = (n) => String(n).padStart(2, "0");
+    return `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}`;
+}
+export function slugify(text, max = 48) {
+    const s = text
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (s.length <= max)
+        return s || "item";
+    const cut = s.slice(0, max);
+    const at = cut.lastIndexOf("-");
+    return (at > max / 2 ? cut.slice(0, at) : cut).replace(/-+$/, "");
+}
+// First free slug in `taken`, suffixing -2, -3... on a clash.
+export function uniqueSlug(base, taken) {
+    if (!taken.has(base))
+        return base;
+    for (let i = 2;; i++) {
+        const next = `${base.slice(0, 56)}-${i}`;
+        if (!taken.has(next))
+            return next;
+    }
+}

package/dist/src/core/vocab.js

@@ -0,0 +1,14 @@
+// Zod-free vocabulary, so the dashboard can import it without bundling the schema.
+export const PHASES = ["now", "next", "later", "wayLater", "maybe"];
+export const STATUSES = ["planned", "partial", "done", "dropped"];
+export const OPEN_STATUSES = ["planned", "partial"];
+export const SIZES = ["S", "M", "L"];
+export const POINTER_KEYS = ["files", "seam", "depends", "trap", "how", "check", "options", "where"];
+export const PHASE_LABEL = {
+    now: "now",
+    next: "next",
+    later: "later",
+    wayLater: "way later",
+    maybe: "maybe",
+};
+export const isOpenStatus = (status) => OPEN_STATUSES.includes(status);

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@uplift-beyond/upgo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Structured goals for every project: a validating CLI for agents, a slim generated goals.md, and a local dashboard.",
+  "author": "uplift-beyond.de",
+  "homepage": "https://uplift-beyond.de/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JennyTheGem/upgo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JennyTheGem/upgo/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "upgo": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "web/dist",
+    "skill"
+  ],
+  "scripts": {
+    "ui": "node cli.ts ui",
+    "dev": "vite",
+    "build": "vite build",
+    "schema": "node scripts/emit-schema.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:cli": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "prepack": "npm run build && npm run build:cli"
+  },
+  "dependencies": {
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^7.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^24.12.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^10.3.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.6.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.59.2",
+    "vite": "^8.0.12",
+    "vitest": "^4.1.10"
+  },
+  "overrides": {
+    "minimatch": "^11.0.1"
+  }
+}