@mutka-explorer/create 1.0.0-rc.1

package/README.md

@@ -0,0 +1,48 @@
+# @mutka-explorer/create
+
+Scaffold a new [Mutka](https://github.com/ilianAZZ/mutka) module — a typed
+TypeScript project wired to [`@mutka-explorer/module`](https://www.npmjs.com/package/@mutka-explorer/module)
+that builds to a single self-contained ESM file (what Mutka loads).
+
+## Usage
+
+```bash
+npm create @mutka-explorer@latest my-module
+# or
+npx @mutka-explorer/create my-module
+```
+
+It prompts for the module id (`author.name`), display name, GitHub username, and
+permissions, then generates:
+
+```text
+my-module/
+  src/index.ts          ← typed skeleton with a working command
+  package.json          ← pins @mutka-explorer/module + a tsup build
+  tsconfig.json
+  mutka.config.json     ← points GitHub discovery at dist/index.js
+  scripts/dev-install.mjs
+  README.md
+```
+
+### Non-interactive
+
+```bash
+npm create @mutka-explorer@latest my-module -- \
+  --yes --author you --name "My Module" --permissions "fs:read,ui" --no-install
+```
+
+Flags: `--id`, `--name`, `--description`, `--author`, `--permissions` (comma-separated),
+`--yes` (accept defaults), `--no-install`, `--pm <npm|pnpm|yarn>`.
+
+## After scaffolding
+
+```bash
+cd my-module
+npm install
+npm run install:local   # build + copy into ~/.mutka/modules/<id>/, then reload Mutka
+```
+
+Edit `src/index.ts` — `host` is fully typed. The module runs isolated in a Web
+Worker (no DOM, no native network; use `host.net`). See the
+[developer guide](https://github.com/ilianAZZ/mutka/blob/main/COMMUNITY_MODULES.md).

package/bin/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Entry point for `npm create @mutka-explorer` / `npx @mutka-explorer/create`.
+import { main } from "../lib/main.mjs";
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`\n✖ ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});

package/lib/main.mjs

@@ -0,0 +1,109 @@
+// Orchestrates the scaffolder: parse args, fill gaps interactively, validate,
+// then write the project and install. Kept dependency-free.
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { resolve, basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ask, confirm } from "./prompt.mjs";
+import { PERMISSIONS } from "./templates.mjs";
+import { writeProject, installDeps, detectPackageManager } from "./scaffold.mjs";
+
+const ID_RE = /^[a-z0-9][a-z0-9-]*\.[a-z0-9][a-z0-9-]*$/;
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+/** This CLI's own version → the @mutka-explorer/module version we pin (lockstep). */
+function typesVersion() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const v = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version;
+  return !v || v === "0.0.0" ? "latest" : `^${v}`;
+}
+
+export async function main(argv) {
+  // `--no-install` isn't native to parseArgs; pull it out before parsing.
+  const skipInstall = argv.includes("--no-install");
+  const args = argv.filter((a) => a !== "--no-install");
+
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      id: { type: "string" },
+      name: { type: "string" },
+      description: { type: "string" },
+      author: { type: "string" },
+      permissions: { type: "string" },
+      yes: { type: "boolean", short: "y", default: false },
+      pm: { type: "string" },
+    },
+  });
+  const auto = values.yes;
+
+  console.log("\n🧩  create-mutka-module\n");
+
+  // Target directory (positional, or asked, defaulting to a name-derived slug).
+  let dir = positionals[0];
+  if (!dir && !auto) dir = await ask("Project directory", "my-mutka-module");
+  dir = dir || "my-mutka-module";
+  const dirName = basename(resolve(dir));
+
+  const defaultName = values.name ?? (auto ? dirName : await ask("Display name", dirName));
+  const authorGithub =
+    values.author ?? (auto ? "" : await ask("Your GitHub username", ""));
+  const defaultId =
+    values.id ?? `${slug(authorGithub) || "you"}.${slug(defaultName) || dirName}`;
+  const id = auto ? defaultId : await ask("Module id (author.name)", defaultId);
+  if (!ID_RE.test(id)) {
+    throw new Error(`invalid module id "${id}" — use the form author.name (lowercase, e.g. you.my-module)`);
+  }
+
+  const description =
+    values.description ?? (auto ? "A Mutka module." : await ask("Description", "A Mutka module."));
+
+  let permissions;
+  if (values.permissions !== undefined) {
+    permissions = values.permissions.split(",").map((p) => p.trim()).filter(Boolean);
+  } else if (auto) {
+    permissions = ["fs:read"];
+  } else {
+    console.log(`\n   Available permissions: ${PERMISSIONS.join(", ")}`);
+    const raw = await ask("Permissions (comma-separated)", "fs:read");
+    permissions = raw.split(",").map((p) => p.trim()).filter(Boolean);
+  }
+  const unknown = permissions.filter((p) => !PERMISSIONS.includes(p));
+  if (unknown.length) throw new Error(`unknown permission(s): ${unknown.join(", ")}`);
+
+  const cfg = {
+    id,
+    name: defaultName,
+    description,
+    authorName: authorGithub || "",
+    authorGithub,
+    permissions,
+    pkgName: slug(dirName) || "mutka-module",
+    typesVersion: typesVersion(),
+  };
+
+  const target = resolve(dir);
+  writeProject(target, cfg);
+  console.log(`\n✓ created ${dir}/  (id: ${id}, permissions: ${permissions.join(", ")})`);
+
+  const doInstall = skipInstall ? false : auto ? true : await confirm("Install dependencies now?", true);
+  if (doInstall) {
+    const pm = values.pm ?? detectPackageManager();
+    console.log(`\nInstalling with ${pm}…\n`);
+    try {
+      installDeps(target, pm);
+    } catch {
+      console.log(`\n⚠ install failed — run it yourself: cd ${dir} && ${pm} install`);
+    }
+  }
+
+  console.log(`
+Next steps:
+  cd ${dir}${doInstall ? "" : "\n  npm install"}
+  npm run install:local   # build + load into Mutka, then reload the app
+  # edit src/index.ts — host is fully typed
+
+Docs: https://github.com/ilianAZZ/mutka/blob/main/COMMUNITY_MODULES.md
+`);
+}

package/lib/prompt.mjs

@@ -0,0 +1,23 @@
+// Minimal interactive prompts over Node's built-in readline — no dependencies,
+// so the CLI runs instantly via npx with nothing to install.
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+/** Ask a free-text question with an optional default shown in brackets. */
+export async function ask(question, fallback = "") {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const hint = fallback ? ` (${fallback})` : "";
+    const answer = (await rl.question(`${question}${hint}: `)).trim();
+    return answer || fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+/** Ask a yes/no question. Returns a boolean; `def` is used on empty input. */
+export async function confirm(question, def = true) {
+  const ans = (await ask(`${question} ${def ? "[Y/n]" : "[y/N]"}`)).toLowerCase();
+  if (!ans) return def;
+  return ans.startsWith("y");
+}

package/lib/scaffold.mjs

@@ -0,0 +1,44 @@
+// Writes the project files to disk and (optionally) installs dependencies.
+import { mkdirSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { execSync } from "node:child_process";
+import {
+  indexTs, packageJson, tsconfigJson, mutkaConfigJson, gitignore, devInstallMjs, readme,
+} from "./templates.mjs";
+
+/** Detect the package manager that invoked us (npm create / yarn create / pnpm). */
+export function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? "";
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("yarn")) return "yarn";
+  return "npm";
+}
+
+function writeFileEnsuring(path, contents) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, contents);
+}
+
+/** Create the project directory tree. Throws if the target exists and is non-empty. */
+export function writeProject(dir, cfg) {
+  if (existsSync(dir) && readdirSync(dir).length > 0) {
+    throw new Error(`target directory "${dir}" already exists and is not empty`);
+  }
+  const files = {
+    "package.json": packageJson(cfg),
+    "tsconfig.json": tsconfigJson(),
+    "mutka.config.json": mutkaConfigJson(),
+    ".gitignore": gitignore(),
+    "README.md": readme(cfg),
+    "src/index.ts": indexTs(cfg),
+    "scripts/dev-install.mjs": devInstallMjs(),
+  };
+  for (const [rel, contents] of Object.entries(files)) {
+    writeFileEnsuring(join(dir, rel), contents);
+  }
+}
+
+/** Install dependencies in `dir` with the given package manager. Best-effort. */
+export function installDeps(dir, pm) {
+  execSync(`${pm} install`, { cwd: dir, stdio: "inherit" });
+}

package/lib/templates.mjs

@@ -0,0 +1,159 @@
+// The files a scaffolded module project is made of. Each function takes the
+// resolved config and returns file contents as a string. Kept here so `main`/
+// `scaffold` stay about orchestration, not text.
+
+/** Every permission a module may declare (mirrors ModulePermission in the app). */
+export const PERMISSIONS = [
+  "fs:read", "fs:write", "fs:temp",
+  "clipboard:read", "clipboard:write",
+  "navigation", "view", "dialog",
+  "network:public", "network:local",
+  "storage", "secrets", "ui", "discovery", "shell",
+];
+
+const permsLiteral = (perms) => perms.map((p) => `"${p}"`).join(", ");
+
+export function indexTs(cfg) {
+  return `import type { SandboxModuleDef } from "@mutka-explorer/module";
+
+// A Mutka module is a single self-contained ESM file. It imports NOTHING at
+// runtime — it reaches the system only through \`host\`, and every host call is
+// checked against the permissions declared below. \`import type\` above is erased
+// at compile time, so the built file stays self-contained.
+const mod: SandboxModuleDef = {
+  id: "${cfg.id}",
+  name: "${cfg.name}",
+  version: "0.1.0",
+  description: "${cfg.description}",
+  author: { name: "${cfg.authorName}", github: "${cfg.authorGithub}" },
+  tags: [],
+  permissions: [${permsLiteral(cfg.permissions)}],
+  commands: [
+    {
+      id: "${cfg.id}.hello",
+      label: "${cfg.name}: count items here",
+      contextMenu: true,
+      contextMenuCategory: "View",
+      when: { selection: "any" },
+    },
+  ],
+  setup(host) {
+    host.onCommand("${cfg.id}.hello", async (snap) => {
+      // host is fully typed — readDir resolves to FileItem[], no cast needed.
+      const items = await host.fs.readDir(snap.currentDirectory);
+      const dirs = items.filter((i) => i.isDir).length;
+      host.log(
+        \`\${snap.currentDirectory} → \${items.length} items (\${dirs} folders, \${items.length - dirs} files)\`,
+      );
+    });
+  },
+};
+
+export default mod;
+`;
+}
+
+export function packageJson(cfg) {
+  return JSON.stringify(
+    {
+      name: cfg.pkgName,
+      version: "0.1.0",
+      description: cfg.description,
+      type: "module",
+      private: true,
+      // Read by scripts/dev-install.mjs to place the built file under ~/.mutka.
+      mutka: { id: cfg.id },
+      scripts: {
+        build: "tsup src/index.ts --format esm",
+        dev: "tsup src/index.ts --format esm --watch",
+        "install:local": "npm run build && node scripts/dev-install.mjs",
+      },
+      devDependencies: {
+        "@mutka-explorer/module": cfg.typesVersion,
+        tsup: "^8.0.0",
+        typescript: "^5.5.0",
+      },
+    },
+    null,
+    2,
+  ) + "\n";
+}
+
+export function tsconfigJson() {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ES2020",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        lib: ["ES2020", "DOM", "DOM.Iterable"],
+        strict: true,
+        skipLibCheck: true,
+        noEmit: true,
+        types: [],
+      },
+      include: ["src"],
+    },
+    null,
+    2,
+  ) + "\n";
+}
+
+// GitHub discovery installs a repo named `mutka-module-*` by reading either a
+// bare index.js at the root OR this file listing the built entry path(s).
+export function mutkaConfigJson() {
+  return JSON.stringify({ projects: ["dist/index.js"] }, null, 2) + "\n";
+}
+
+export function gitignore() {
+  return ["node_modules/", "*.log", ".DS_Store", ""].join("\n");
+}
+
+// Builds, then copies the single bundled file into ~/.mutka/modules/<id>/ so the
+// running app picks it up on reload — the fast local dev loop.
+export function devInstallMjs() {
+  return `import { readFileSync, mkdirSync, copyFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+const id = pkg.mutka?.id;
+if (!id) throw new Error("package.json is missing \\"mutka.id\\"");
+if (!existsSync("dist/index.js")) throw new Error("dist/index.js not found — run \\"npm run build\\" first");
+
+const dest = join(homedir(), ".mutka", "modules", id);
+mkdirSync(dest, { recursive: true });
+copyFileSync("dist/index.js", join(dest, "index.js"));
+console.log(\`installed → \${join(dest, "index.js")}\\nReload Mutka (or toggle the module) to load it.\`);
+`;
+}
+
+export function readme(cfg) {
+  return `# ${cfg.name}
+
+A [Mutka](https://github.com/ilianAZZ/mutka) module (\`${cfg.id}\`), written in
+TypeScript against [\`@mutka-explorer/module\`](https://www.npmjs.com/package/@mutka-explorer/module).
+
+## Develop
+
+\`\`\`bash
+npm install
+npm run dev          # rebuild dist/index.js on change
+npm run install:local # build + copy into ~/.mutka/modules/${cfg.id}/ then reload Mutka
+\`\`\`
+
+Your module logic lives in \`src/index.ts\`. It runs ISOLATED in a Web Worker:
+**no DOM, no native network** (\`fetch\`/\`XMLHttpRequest\`/\`WebSocket\` are blocked —
+use \`host.net\`). Pure-logic npm libraries bundle fine; DOM/network ones do not.
+
+## Build & publish
+
+\`\`\`bash
+npm run build        # bundles src/index.ts → dist/index.js (one self-contained file)
+\`\`\`
+
+To distribute via Mutka's GitHub discovery, push this project to a repo named
+\`mutka-module-*\` with \`dist/index.js\` committed; \`mutka.config.json\` points the
+catalog at it. Users then find and install it from the Modules overlay.
+`;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mutka-explorer/create",
+  "version": "1.0.0-rc.1",
+  "description": "Scaffold a new Mutka module — a typed TypeScript project wired to @mutka-explorer/module that builds to a single ESM file.",
+  "license": "MIT",
+  "author": "Mutka contributors",
+  "homepage": "https://github.com/ilianAZZ/mutka",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ilianAZZ/mutka.git",
+    "directory": "packages/create-module"
+  },
+  "keywords": [
+    "mutka",
+    "module",
+    "create",
+    "scaffold",
+    "file-explorer"
+  ],
+  "type": "module",
+  "bin": {
+    "create-mutka-module": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}