@dot-skill/workspace 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bharat Dudeja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Local skill workspace — git-like working tree for `.skill`.
+ *
+ * Layout:
+ *   .skill/
+ *     config.json
+ *     sections/<id>.json       # proposed units (AI agent)
+ *     index.json               # staged ids
+ *     HEAD.json                # last compiled package
+ *     objects/<id>.skill       # continuity drafts / release packages
+ */
+import type { CompletenessReport, GenerationUsage, SectionType, SkillCompileProfile, SkillSource } from "@dot-skill/protocol";
+import { type CompileResult } from "@dot-skill/core";
+export declare const WORKSPACE_DIR = ".skill";
+export interface WorkspaceSection {
+    kind: "section";
+    id: string;
+    type: SectionType;
+    title: string;
+    body: string;
+    fidelity: "exact" | "synthesize";
+    created_at: string;
+    updated_at: string;
+    /** Always agent-authored in valid workflows. */
+    source: "agent";
+    meta?: Record<string, unknown>;
+}
+export interface WorkspaceIndex {
+    staged: string[];
+    updated_at: string;
+}
+export interface WorkspaceConfig {
+    version: 1;
+    title?: string;
+    default_stage_all: boolean;
+    created_at: string;
+    journey_summary?: string;
+    open_questions?: string[];
+}
+export interface WorkspaceHead {
+    package_path?: string;
+    package_digest?: string;
+    skill_id?: string;
+    mint_status?: "draft" | "minted";
+    compile_profile?: SkillCompileProfile;
+    updated_at: string;
+}
+export declare function requireAgentHost(host?: string): string;
+export declare function findWorkspaceRoot(start?: string): string | undefined;
+export declare function requireWorkspace(cwd?: string): string;
+export declare function initWorkspace(cwd?: string, opts?: {
+    title?: string;
+}): Promise<{
+    root: string;
+    created: boolean;
+}>;
+export declare function loadConfig(root: string): Promise<WorkspaceConfig>;
+export declare function saveConfig(root: string, config: WorkspaceConfig): Promise<void>;
+export declare function loadIndex(root: string): Promise<WorkspaceIndex>;
+export declare function loadHead(root: string): Promise<WorkspaceHead>;
+export declare function listSections(root: string): Promise<WorkspaceSection[]>;
+/** @deprecated use listSections */
+export declare const listIngredients: typeof listSections;
+export declare function proposeSection(root: string, input: {
+    title: string;
+    body: string;
+    type?: SectionType;
+    fidelity?: "exact" | "synthesize";
+    id?: string;
+    host?: string;
+}): Promise<WorkspaceSection>;
+/** @deprecated use proposeSection */
+export declare const proposeIngredient: typeof proposeSection;
+export declare function proposeMany(root: string, items: Array<{
+    title: string;
+    body: string;
+    type?: SectionType;
+    fidelity?: "exact" | "synthesize";
+}>, host?: string): Promise<WorkspaceSection[]>;
+export declare function setJourney(root: string, journey: {
+    summary: string;
+    open_questions?: string[];
+}): Promise<WorkspaceConfig>;
+export declare function stage(root: string, ids: string[] | "all"): Promise<WorkspaceIndex>;
+export declare function unstage(root: string, ids: string[] | "all"): Promise<WorkspaceIndex>;
+export interface StatusResult {
+    root: string;
+    title?: string;
+    unstaged: WorkspaceSection[];
+    staged: WorkspaceSection[];
+    head: WorkspaceHead;
+    completeness?: CompletenessReport;
+    journey_summary?: string;
+    agent_host_ok: boolean;
+}
+export declare function status(root: string): Promise<StatusResult>;
+export interface CompileWorkspaceOptions {
+    title?: string;
+    summary?: string;
+    message?: string;
+    add_all?: boolean;
+    approve?: boolean;
+    mint?: boolean;
+    profile?: SkillCompileProfile;
+    host?: string;
+    generation_usage?: GenerationUsage;
+    input_tokens?: number;
+    output_tokens?: number;
+}
+export interface CompileWorkspaceResult {
+    source: SkillSource;
+    compile: CompileResult;
+    package_path: string;
+    minted?: boolean;
+    package_digest: string;
+    profile: SkillCompileProfile;
+}
+/**
+ * Continuity checkpoint — partial OK, privacy-scrubbed handoff draft.
+ */
+export declare function checkpoint(root: string, opts?: CompileWorkspaceOptions): Promise<CompileWorkspaceResult>;
+/**
+ * Compile staged sections → `.skill`.
+ * release profile refuses if incomplete; continuity allows partial.
+ */
+export declare function compileWorkspace(root: string, opts?: CompileWorkspaceOptions): Promise<CompileWorkspaceResult>;
+/** @deprecated use compileWorkspace — Skillerr product term */
+export declare function bake(root: string, opts?: CompileWorkspaceOptions & {
+    publish?: boolean;
+}): Promise<CompileWorkspaceResult & {
+    published?: boolean;
+}>;
+export declare function discardSection(root: string, sectionId: string): Promise<void>;
+/** @deprecated */
+export declare const discardIngredient: typeof discardSection;
+/** Load a continuity/release package for agent handoff resume. */
+export declare function loadSkillHandoff(packagePath: string): Promise<{
+    skill_id: string;
+    title: string;
+    intent?: string;
+    journey?: unknown;
+    generation_usage?: unknown;
+    completeness?: CompletenessReport;
+    compile_profile?: SkillCompileProfile;
+    knowledge: Array<{
+        id: string;
+        title: string;
+        type: string;
+    }>;
+    open_questions?: string[];
+    mint_status?: string;
+}>;

package/dist/index.js

@@ -0,0 +1,446 @@
+/**
+ * Local skill workspace — git-like working tree for `.skill`.
+ *
+ * Layout:
+ *   .skill/
+ *     config.json
+ *     sections/<id>.json       # proposed units (AI agent)
+ *     index.json               # staged ids
+ *     HEAD.json                # last compiled package
+ *     objects/<id>.skill       # continuity drafts / release packages
+ */
+import { mkdir, readFile, writeFile, readdir, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { isValidAgentHost, PROTOCOL_VERSION } from "@dot-skill/protocol";
+import { compileSkillSource, approveCompilation, mintSkillPackage, redactSecrets, CompileRefusalError, } from "@dot-skill/core";
+export const WORKSPACE_DIR = ".skill";
+function id(prefix) {
+    return `${prefix}_${createHash("sha256").update(randomUUID()).digest("hex").slice(0, 12)}`;
+}
+export function requireAgentHost(host) {
+    const h = host ?? process.env.SKILL_HOST;
+    if (!isValidAgentHost(h)) {
+        throw new Error("AI agent provenance required. Set SKILL_HOST=cursor|ollama|lmstudio|llama-cpp|custom-agent|… (local models are supported).");
+    }
+    return h;
+}
+export function findWorkspaceRoot(start = process.cwd()) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, WORKSPACE_DIR, "config.json")))
+            return dir;
+        const parent = resolve(dir, "..");
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+export function requireWorkspace(cwd = process.cwd()) {
+    const root = findWorkspaceRoot(cwd);
+    if (!root) {
+        throw new Error(`Not a skill workspace (or any parent). Run: skill init`);
+    }
+    return root;
+}
+function paths(root) {
+    const base = join(root, WORKSPACE_DIR);
+    return {
+        base,
+        config: join(base, "config.json"),
+        index: join(base, "index.json"),
+        head: join(base, "HEAD.json"),
+        sections: join(base, "sections"),
+        /** @deprecated migrated from ingredients/ */
+        ingredientsLegacy: join(base, "ingredients"),
+        objects: join(base, "objects"),
+    };
+}
+export async function initWorkspace(cwd = process.cwd(), opts = {}) {
+    const root = resolve(cwd);
+    const p = paths(root);
+    if (existsSync(p.config)) {
+        return { root, created: false };
+    }
+    await mkdir(p.sections, { recursive: true });
+    await mkdir(p.objects, { recursive: true });
+    const config = {
+        version: 1,
+        title: opts.title,
+        default_stage_all: true,
+        created_at: new Date().toISOString(),
+    };
+    const index = { staged: [], updated_at: new Date().toISOString() };
+    const head = { updated_at: new Date().toISOString() };
+    await writeFile(p.config, JSON.stringify(config, null, 2) + "\n");
+    await writeFile(p.index, JSON.stringify(index, null, 2) + "\n");
+    await writeFile(p.head, JSON.stringify(head, null, 2) + "\n");
+    await writeFile(join(p.base, "README"), "Open .skill workspace. AI agent: skill propose → skill checkpoint|compile → skill mint.\nHuman reviews/stages; only agents create.\n");
+    return { root, created: true };
+}
+async function readJson(path) {
+    return JSON.parse(await readFile(path, "utf8"));
+}
+export async function loadConfig(root) {
+    return readJson(paths(root).config);
+}
+export async function saveConfig(root, config) {
+    await writeFile(paths(root).config, JSON.stringify(config, null, 2) + "\n");
+}
+export async function loadIndex(root) {
+    return readJson(paths(root).index);
+}
+export async function loadHead(root) {
+    const p = paths(root).head;
+    if (!existsSync(p))
+        return { updated_at: new Date().toISOString() };
+    return readJson(p);
+}
+async function listSectionFiles(root) {
+    const p = paths(root);
+    const dirs = [p.sections, p.ingredientsLegacy].filter((d) => existsSync(d));
+    const out = [];
+    const seen = new Set();
+    for (const dir of dirs) {
+        const files = (await readdir(dir)).filter((f) => f.endsWith(".json"));
+        for (const f of files) {
+            const raw = await readJson(join(dir, f));
+            const section = {
+                kind: "section",
+                id: raw.id,
+                type: raw.type,
+                title: raw.title,
+                body: raw.body,
+                fidelity: raw.fidelity ?? "exact",
+                created_at: raw.created_at,
+                updated_at: raw.updated_at,
+                source: "agent",
+                meta: raw.meta,
+            };
+            if (!seen.has(section.id)) {
+                seen.add(section.id);
+                out.push(section);
+            }
+        }
+    }
+    return out.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+export async function listSections(root) {
+    return listSectionFiles(root);
+}
+/** @deprecated use listSections */
+export const listIngredients = listSections;
+export async function proposeSection(root, input) {
+    requireAgentHost(input.host);
+    const section = {
+        kind: "section",
+        id: input.id ?? id("sec"),
+        type: input.type ?? "implementation_note",
+        title: input.title,
+        body: input.body,
+        fidelity: input.fidelity ?? "exact",
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+        source: "agent",
+    };
+    await mkdir(paths(root).sections, { recursive: true });
+    await writeFile(join(paths(root).sections, `${section.id}.json`), JSON.stringify(section, null, 2) + "\n");
+    const config = await loadConfig(root);
+    if (config.default_stage_all) {
+        await stage(root, [section.id]);
+    }
+    return section;
+}
+/** @deprecated use proposeSection */
+export const proposeIngredient = proposeSection;
+export async function proposeMany(root, items, host) {
+    requireAgentHost(host);
+    const out = [];
+    for (const item of items) {
+        out.push(await proposeSection(root, { ...item, host }));
+    }
+    return out;
+}
+export async function setJourney(root, journey) {
+    const config = await loadConfig(root);
+    config.journey_summary = redactSecrets(journey.summary);
+    config.open_questions = journey.open_questions?.map(redactSecrets);
+    await saveConfig(root, config);
+    return config;
+}
+export async function stage(root, ids) {
+    const all = await listSections(root);
+    const byId = new Map(all.map((i) => [i.id, i]));
+    const index = await loadIndex(root);
+    const add = ids === "all" ? all.map((i) => i.id) : ids;
+    for (const secId of add) {
+        if (!byId.has(secId))
+            throw new Error(`Unknown section: ${secId}`);
+        if (!index.staged.includes(secId))
+            index.staged.push(secId);
+    }
+    index.updated_at = new Date().toISOString();
+    await writeFile(paths(root).index, JSON.stringify(index, null, 2) + "\n");
+    return index;
+}
+export async function unstage(root, ids) {
+    const index = await loadIndex(root);
+    if (ids === "all")
+        index.staged = [];
+    else
+        index.staged = index.staged.filter((x) => !ids.includes(x));
+    index.updated_at = new Date().toISOString();
+    await writeFile(paths(root).index, JSON.stringify(index, null, 2) + "\n");
+    return index;
+}
+export async function status(root) {
+    const config = await loadConfig(root);
+    const index = await loadIndex(root);
+    const all = await listSections(root);
+    const stagedSet = new Set(index.staged);
+    const staged = all.filter((i) => stagedSet.has(i.id));
+    let completeness;
+    try {
+        if (staged.length) {
+            const source = await toSkillSource(root, staged, "status", "continuity");
+            const { assessCompleteness } = await import("@dot-skill/core");
+            completeness = assessCompleteness(source, {
+                profile: "release",
+                hasWorkflowAction: staged.some((s) => ["integration", "prompt", "implementation_note", "workflow_note", "code"].includes(s.type)),
+                hasKnowledge: staged.length > 0,
+                hasInputsDeclared: true,
+                pendingApprovals: [],
+            });
+        }
+    }
+    catch {
+        // status should not throw on incomplete
+    }
+    return {
+        root,
+        title: config.title,
+        staged,
+        unstaged: all.filter((i) => !stagedSet.has(i.id)),
+        head: await loadHead(root),
+        completeness,
+        journey_summary: config.journey_summary,
+        agent_host_ok: isValidAgentHost(process.env.SKILL_HOST),
+    };
+}
+async function toSkillSource(root, staged, title, profile, usage, hostOverride) {
+    const host = requireAgentHost(hostOverride);
+    const config = await loadConfig(root);
+    const sections = staged.map((i) => ({
+        id: i.id,
+        revision: 1,
+        type: i.type,
+        title: i.title,
+        body: i.body,
+        attachments: [],
+        code_refs: [],
+        sensitivity: "shareable_redacted",
+        authored_by: "agent",
+    }));
+    const sid = id("src");
+    const hash = "sha256:" +
+        createHash("sha256")
+            .update(title + staged.map((s) => s.body).join(""))
+            .digest("hex");
+    return {
+        kind: "skill_source",
+        id: sid,
+        hash,
+        title,
+        summary: config.journey_summary ?? title,
+        intent: config.title ?? title,
+        sections,
+        steering: [],
+        prompts: [],
+        code_refs: [],
+        parents: [],
+        agent: {
+            host,
+            provider: process.env.SKILL_PROVIDER,
+            model: process.env.SKILL_MODEL,
+            runtime: process.env.SKILL_AGENT_RUNTIME ?? "@dot-skill/cli",
+            deployment: process.env.SKILL_DEPLOYMENT ?? "unknown",
+            endpoint: process.env.SKILL_ENDPOINT
+                ? redactSecrets(process.env.SKILL_ENDPOINT)
+                : undefined,
+            session_ids: process.env.SKILL_SESSION_ID ? [process.env.SKILL_SESSION_ID] : [],
+        },
+        journey: {
+            summary: config.journey_summary ??
+                `Human+AI work on "${title}" (${staged.length} sections). Profile=${profile}.`,
+            open_questions: config.open_questions,
+            decisions: staged.filter((s) => s.type === "decision").map((s) => s.title),
+            redacted: true,
+            sensitivity: "shareable_redacted",
+        },
+        generation_usage: usage,
+        inputs_declared: "none",
+        sensitivity: "shareable_redacted",
+        created_at: new Date().toISOString(),
+        actor: { id: process.env.SKILL_ACTOR ?? "human" },
+        source_protocol_version: PROTOCOL_VERSION,
+    };
+}
+/**
+ * Continuity checkpoint — partial OK, privacy-scrubbed handoff draft.
+ */
+export async function checkpoint(root, opts = {}) {
+    return compileWorkspace(root, { ...opts, profile: "continuity", mint: false });
+}
+/**
+ * Compile staged sections → `.skill`.
+ * release profile refuses if incomplete; continuity allows partial.
+ */
+export async function compileWorkspace(root, opts = {}) {
+    requireAgentHost(opts.host);
+    const profile = opts.profile ?? "release";
+    if (opts.add_all !== false) {
+        await stage(root, "all");
+    }
+    const st = await status(root);
+    if (st.staged.length === 0) {
+        throw new Error("Nothing staged. Agent must propose sections first (`skill propose`), then `skill add`.");
+    }
+    const title = opts.title ?? opts.message ?? (await loadConfig(root)).title ?? st.staged[0].title;
+    if (opts.summary) {
+        await setJourney(root, { summary: opts.summary, open_questions: undefined });
+    }
+    const usage = opts.generation_usage ??
+        (opts.input_tokens || opts.output_tokens
+            ? {
+                input_tokens: opts.input_tokens,
+                output_tokens: opts.output_tokens,
+                total_tokens: (opts.input_tokens ?? 0) + (opts.output_tokens ?? 0),
+                reported_by: "agent",
+                captured_at: new Date().toISOString(),
+                host: process.env.SKILL_HOST,
+                model: process.env.SKILL_MODEL,
+            }
+            : parseUsageFromEnv());
+    const source = await toSkillSource(root, st.staged, title, profile, usage, opts.host);
+    let compiled;
+    try {
+        compiled = compileSkillSource(source, {
+            title,
+            description: opts.summary ?? opts.message,
+            profile,
+            approve_inferred_inputs: opts.approve === true,
+            approve_permissions: opts.approve === true,
+            generation_usage: usage,
+            provenance_mode: profile === "continuity" ? "redacted" : "full",
+        });
+    }
+    catch (e) {
+        if (e instanceof CompileRefusalError) {
+            throw e;
+        }
+        throw e;
+    }
+    if (opts.approve === true) {
+        compiled = approveCompilation(compiled, { inputs: ["*"], permissions: true });
+    }
+    let bytes = compiled.packageBytes;
+    let minted = false;
+    if (opts.mint) {
+        if (profile !== "release") {
+            throw new Error("Mint only allowed with --profile release (not continuity drafts).");
+        }
+        const sealed = mintSkillPackage(compiled.files, {
+            host: requireAgentHost(opts.host),
+            provider: process.env.SKILL_PROVIDER,
+            model: process.env.SKILL_MODEL,
+            deployment: process.env.SKILL_DEPLOYMENT ?? "unknown",
+            endpoint: process.env.SKILL_ENDPOINT
+                ? redactSecrets(process.env.SKILL_ENDPOINT)
+                : undefined,
+            actors: [process.env.SKILL_ACTOR ?? "human"],
+            agent_runtime: process.env.SKILL_AGENT_RUNTIME ?? "@dot-skill/cli",
+        });
+        bytes = sealed.packageBytes;
+        compiled = { ...compiled, files: sealed.files, packageBytes: sealed.packageBytes };
+        minted = true;
+    }
+    const digest = compiled.files.manifest.package_digest;
+    const outName = `${compiled.files.manifest.id}.skill`;
+    const package_path = join(paths(root).objects, outName);
+    await writeFile(package_path, bytes);
+    const head = {
+        package_path,
+        package_digest: digest,
+        skill_id: compiled.files.manifest.id,
+        mint_status: minted ? "minted" : "draft",
+        compile_profile: profile,
+        updated_at: new Date().toISOString(),
+    };
+    await writeFile(paths(root).head, JSON.stringify(head, null, 2) + "\n");
+    await writeFile(join(root, outName), bytes);
+    return {
+        source,
+        compile: compiled,
+        package_path,
+        minted,
+        package_digest: digest,
+        profile,
+    };
+}
+/** @deprecated use compileWorkspace — Skillerr product term */
+export async function bake(root, opts = {}) {
+    if (opts.publish) {
+        throw new Error("publish is not part of the open protocol happy path. Share the .skill file, or use a product registry later.");
+    }
+    return compileWorkspace(root, opts);
+}
+function parseUsageFromEnv() {
+    const input = process.env.SKILL_INPUT_TOKENS
+        ? Number(process.env.SKILL_INPUT_TOKENS)
+        : undefined;
+    const output = process.env.SKILL_OUTPUT_TOKENS
+        ? Number(process.env.SKILL_OUTPUT_TOKENS)
+        : undefined;
+    if (input == null && output == null)
+        return undefined;
+    return {
+        input_tokens: input,
+        output_tokens: output,
+        total_tokens: (input ?? 0) + (output ?? 0),
+        reported_by: "agent",
+        captured_at: new Date().toISOString(),
+        host: process.env.SKILL_HOST,
+        model: process.env.SKILL_MODEL,
+    };
+}
+export async function discardSection(root, sectionId) {
+    const p = paths(root);
+    for (const dir of [p.sections, p.ingredientsLegacy]) {
+        const file = join(dir, `${sectionId}.json`);
+        if (existsSync(file))
+            await unlink(file);
+    }
+    await unstage(root, [sectionId]);
+}
+/** @deprecated */
+export const discardIngredient = discardSection;
+/** Load a continuity/release package for agent handoff resume. */
+export async function loadSkillHandoff(packagePath) {
+    const { unpackSkill } = await import("@dot-skill/core");
+    const bytes = new Uint8Array(await readFile(resolve(packagePath)));
+    const u = unpackSkill(bytes);
+    const journey = u.raw.provenance?.journey;
+    return {
+        skill_id: u.manifest.id,
+        title: u.manifest.title,
+        intent: u.manifest.intent,
+        journey: u.raw.provenance?.journey,
+        generation_usage: u.raw.provenance?.generation_usage,
+        completeness: u.manifest.completeness,
+        compile_profile: u.manifest.compile_profile,
+        knowledge: u.knowledge.map((k) => ({ id: k.id, title: k.title, type: k.type })),
+        open_questions: journey?.open_questions,
+        mint_status: u.manifest.mint?.mint_status,
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dot-skill/workspace",
+  "version": "0.4.1",
+  "description": "Git-like local .skill workspace — sections, stage, compile, checkpoint, mint",
+  "license": "MIT",
+  "author": {
+    "name": "Bharat Dudeja",
+    "url": "https://github.com/bharatdudeja13-cmd"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dot-skill/dot-skill.git",
+    "directory": "packages/workspace"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@dot-skill/core": "^0.4.1",
+    "@dot-skill/protocol": "^0.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "typescript": "^5.8.3"
+  }
+}