lineadraw 0.1.0 → 0.3.0

package/bin/lineadraw.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// The `lineadraw` CLI — marketplace tooling for Linea block/command repos.
+//   lineadraw manifest [--dir <path>]   generate .lineadraw/marketplace.json
+//   lineadraw check    [--dir <path>]   validate + fail if the manifest is stale
+//   lineadraw init     [--dir <path>]   add the marketplace structure here
+// See docs/marketplace-devx.md in the linea repo for the design.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  buildManifest,
+  manifestJson,
+  MANIFEST_PATH,
+  verifyWithSdk,
+} from "../lib/manifest.mjs";
+import { init } from "../lib/init.mjs";
+
+const USAGE = `Usage: lineadraw <manifest|check|init> [--dir <path>]
+
+  manifest  Validate all modules and write ${MANIFEST_PATH}
+  check     Validate without writing; fail if the committed manifest is stale
+  init      Add the marketplace structure to the current npm project
+
+With @lineadraw/sdk installed (devDependency), manifest and check also
+dry-run every block. The manifest content is identical either way.`;
+
+const args = process.argv.slice(2);
+const command = args[0];
+const dirFlag = args.indexOf("--dir");
+const dir = resolve(dirFlag === -1 ? "." : (args[dirFlag + 1] ?? "."));
+
+const fail = (message) => {
+  console.error(message);
+  process.exit(1);
+};
+
+const reportProblems = (problems) => {
+  for (const p of problems)
+    console.error(`REJECTED ${p.file}: ${p.problems.join("; ")}`);
+};
+
+/** Validate everything (light + optional sdk dry-run); exits on failure. */
+const validatedManifest = async () => {
+  const { manifest, sources, problems } = buildManifest(dir);
+  const sdkResult = await verifyWithSdk(dir, manifest, sources);
+  const all = [...problems, ...sdkResult.problems];
+  if (all.length > 0) {
+    reportProblems(all);
+    fail(`${all.length} problem(s) — nothing written.`);
+  }
+  if (!sdkResult.ran)
+    console.warn(
+      "The contents of blocks/commands were not dry-run because @lineadraw/sdk is not installed. Install it as a devDependency to enable this check.",
+    );
+  return manifest;
+};
+
+switch (command) {
+  case "manifest": {
+    const manifest = await validatedManifest();
+    const outPath = join(dir, MANIFEST_PATH);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, manifestJson(manifest));
+    console.log(`${MANIFEST_PATH}: ${manifest.entries.length} entries`);
+    for (const e of manifest.entries)
+      console.log(`  ${e.kind}  ${e.id}  v${e.version}`);
+    break;
+  }
+  case "check": {
+    const manifest = await validatedManifest();
+    const committedPath = join(dir, MANIFEST_PATH);
+    const committed = existsSync(committedPath)
+      ? readFileSync(committedPath, "utf8")
+      : null;
+    if (committed !== manifestJson(manifest))
+      fail(
+        `${MANIFEST_PATH} is ${committed === null ? "missing" : "stale"} — run \`npx lineadraw manifest\` and commit the result.`,
+      );
+    console.log(
+      `OK: ${manifest.entries.length} entries, manifest is current.`,
+    );
+    break;
+  }
+  case "init": {
+    try {
+      const { created, skipped } = init(dir);
+      for (const f of created) console.log(`created  ${f}`);
+      for (const f of skipped) console.log(`kept     ${f}`);
+      console.log(
+        "\nDone. Commit, push, then add the repo in the editor: Library → Marketplace.",
+      );
+    } catch (e) {
+      fail(e instanceof Error ? e.message : String(e));
+    }
+    break;
+  }
+  default:
+    fail(USAGE);
+}

package/lib/init.mjs

@@ -0,0 +1,127 @@
+// `lineadraw init` — add the marketplace structure to the CURRENT npm
+// project, whatever it is. Non-destructive: existing files and package.json
+// keys are never overwritten; everything it creates is reported. Ends by
+// generating `.lineadraw/marketplace.json`, so the repo is addable in the
+// editor from the first push.
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildManifest, manifestJson, MANIFEST_PATH } from "./manifest.mjs";
+
+const templatesDir = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "templates",
+);
+const template = (name) => readFileSync(join(templatesDir, name), "utf8");
+
+/** Lowercase-kebab collection slug from a package name (`@scope/` and
+ * illegal characters dropped, per the `@collection/slug` id grammar). */
+export const collectionSlug = (pkgName) => {
+  const slug = String(pkgName ?? "")
+    .replace(/^@[^/]+\//, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return slug === "" ? "my-collection" : slug;
+};
+
+/** Run init in `dir`. Returns `{ created, skipped }` path lists. */
+export const init = (dir) => {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath))
+    throw new Error(
+      "no package.json here — run `npm init` first (or start from an empty folder with `npm create lineadraw`)",
+    );
+  const created = [];
+  const skipped = [];
+  const write = (relPath, content) => {
+    const abs = join(dir, relPath);
+    if (existsSync(abs)) {
+      skipped.push(relPath);
+      return;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    created.push(relPath);
+  };
+
+  // package.json: fill the marketplace config and scripts, never replacing
+  // what is already there.
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  let pkgChanged = false;
+  if (pkg.lineadraw === undefined) {
+    pkg.lineadraw = {
+      marketplaceName: pkg.description ?? pkg.name ?? "Marketplace",
+      marketplaceOwner:
+        typeof pkg.author === "string" ? pkg.author : (pkg.author?.name ?? ""),
+    };
+    pkgChanged = true;
+  }
+  pkg.scripts ??= {};
+  for (const [script, cmd] of [
+    ["manifest", "lineadraw manifest"],
+    ["check", "lineadraw check"],
+  ]) {
+    if (pkg.scripts[script] === undefined) {
+      pkg.scripts[script] = cmd;
+      pkgChanged = true;
+    }
+  }
+  if (pkgChanged) {
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    created.push("package.json (lineadraw config + scripts merged)");
+  }
+
+  const blocksDir = pkg.lineadraw?.blocks ?? "blocks";
+  const commandsDir = pkg.lineadraw?.commands ?? "commands";
+  mkdirSync(join(dir, blocksDir), { recursive: true });
+  mkdirSync(join(dir, commandsDir), { recursive: true });
+
+  // A sample block only when the blocks folder is empty — init on an
+  // existing collection must not inject content.
+  const hasModules = readdirSync(join(dir, blocksDir)).some(
+    (f) => f.endsWith(".ts") || f.endsWith(".js"),
+  );
+  if (!hasModules) {
+    const author = pkg.lineadraw?.marketplaceOwner || "Your Name";
+    write(
+      join(blocksDir, "sample-box.block.ts"),
+      template("sample.block.ts")
+        .replaceAll("__COLLECTION__", collectionSlug(pkg.name))
+        .replaceAll("__AUTHOR__", author),
+    );
+  }
+
+  write(".github/workflows/marketplace.yml", template("workflow.yml"));
+  write("tsconfig.json", template("tsconfig.json"));
+  write(
+    "README.md",
+    template("README.md").replaceAll(
+      "__NAME__",
+      pkg.lineadraw?.marketplaceName ?? pkg.name ?? "Marketplace",
+    ),
+  );
+  write(".gitignore", "node_modules/\n");
+
+  // Generate the catalog last, over whatever modules now exist.
+  const { manifest, problems } = buildManifest(dir);
+  if (problems.length > 0) {
+    const detail = problems
+      .map((p) => `${p.file}: ${p.problems.join("; ")}`)
+      .join("\n");
+    throw new Error(`existing modules failed validation:\n${detail}`);
+  }
+  mkdirSync(join(dir, dirname(MANIFEST_PATH)), { recursive: true });
+  writeFileSync(join(dir, MANIFEST_PATH), manifestJson(manifest));
+  created.push(`${MANIFEST_PATH} (${manifest.entries.length} entries)`);
+
+  return { created, skipped };
+};

package/lib/manifest.mjs

@@ -0,0 +1,225 @@
+// Minimal-manifest generator (docs/marketplace-devx.md in the linea repo).
+// Pure filesystem walk — no git: rows carry repo-RELATIVE `source` paths
+// that the editor resolves against the repo the user added, at the ref the
+// manifest itself was fetched from. Deterministic: same content, same
+// bytes, so `check` is a plain diff.
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// sucrase is this package's own dependency — the light path needs nothing
+// else installed.
+const require_ = createRequire(import.meta.url);
+
+const ID_RE = /^@[a-z0-9-]{1,64}\/[a-z0-9-]{1,64}$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+
+/** Marketplace config resolved from the repo's package.json. */
+export const readConfig = (repoDir) => {
+  const pkgPath = join(repoDir, "package.json");
+  if (!existsSync(pkgPath))
+    throw new Error(`no package.json in ${repoDir} — run \`lineadraw init\` in an npm project`);
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const cfg = pkg.lineadraw ?? {};
+  return {
+    name: cfg.marketplaceName ?? pkg.description ?? pkg.name ?? "Marketplace",
+    owner:
+      cfg.marketplaceOwner ??
+      (typeof pkg.author === "string" ? pkg.author : (pkg.author?.name ?? "")),
+    blocksDir: cfg.blocks ?? "blocks",
+    commandsDir: cfg.commands ?? "commands",
+  };
+};
+
+// Same execution model as @lineadraw/core's transpiler: ESM→CJS, run
+// against a require shim. Helpers resolve to no-op function proxies —
+// top-level code only needs the imports to EXIST; draw()/run() never run
+// here (that is the optional sdk dry-run's job).
+const helperProxy = new Proxy({}, { get: () => () => ({}) });
+
+const executeModule = (source) => {
+  const { transform } = require_("sucrase");
+  const code = transform(source, {
+    transforms: ["typescript", "imports"],
+  }).code;
+  const moduleShim = { exports: {} };
+  new Function("exports", "require", "module", code)(
+    moduleShim.exports,
+    (spec) => {
+      if (spec === "lineadraw" || spec === "linea")
+        return {
+          helpers: helperProxy,
+          defineBlock: (s) => s,
+          defineCommand: (s) => s,
+        };
+      if (spec === "lineadraw/helpers" || spec === "linea/helpers")
+        return helperProxy;
+      throw new Error(`illegal import "${spec}"`);
+    },
+    moduleShim,
+  );
+  const exported = moduleShim.exports;
+  const spec = exported.default;
+  return spec !== null && typeof spec === "object" && !Array.isArray(spec)
+    ? { ...exported, ...spec }
+    : exported;
+};
+
+const entryOf = (kind, repoDir, folder, file) => {
+  const source = readFileSync(join(repoDir, folder, file), "utf8");
+  let mod;
+  try {
+    mod = executeModule(source);
+  } catch (e) {
+    return { file, problems: [`does not compile: ${e.message}`] };
+  }
+  const problems = [];
+  if (typeof mod.id !== "string" || !ID_RE.test(mod.id))
+    problems.push(`id ${JSON.stringify(mod.id)} is not @collection/slug`);
+  if (typeof mod.name !== "string" || mod.name.trim() === "")
+    problems.push("missing name");
+  if (typeof mod.version !== "string" || !SEMVER_RE.test(mod.version))
+    problems.push(`version ${JSON.stringify(mod.version)} is not semver`);
+  if (
+    kind === "block" &&
+    typeof mod.draw !== "function" &&
+    typeof mod.main !== "function"
+  )
+    problems.push("no draw export");
+  if (kind === "command" && typeof mod.run !== "function")
+    problems.push("no run export");
+  if (problems.length > 0) return { file, problems };
+  return {
+    file,
+    source,
+    entry: {
+      kind,
+      id: mod.id,
+      name: mod.name,
+      version: mod.version,
+      ...(typeof mod.description === "string"
+        ? { description: mod.description }
+        : {}),
+      tags: Array.isArray(mod.tags)
+        ? mod.tags.filter((t) => typeof t === "string")
+        : [],
+      authors: Array.isArray(mod.authors)
+        ? mod.authors.filter((a) => typeof a === "string")
+        : [],
+      dependencies:
+        kind === "block" && Array.isArray(mod.dependencies)
+          ? mod.dependencies.filter((d) => typeof d === "string")
+          : [],
+      // POSIX-relative, unencoded — the editor percent-encodes segments
+      // when it builds the fetch URL.
+      source: `${folder}/${file}`,
+    },
+  };
+};
+
+const listModules = (repoDir, folder) =>
+  existsSync(join(repoDir, folder))
+    ? readdirSync(join(repoDir, folder))
+        .filter((f) => f.endsWith(".ts") || f.endsWith(".js"))
+        .sort()
+    : [];
+
+/**
+ * Build the manifest for a marketplace repo. Returns
+ * `{ manifest, sources, problems }`; `problems` is a list of
+ * `{ file, problems }` — a non-empty list means the repo must not publish
+ * (callers fail instead of writing a partial catalog). `sources` maps
+ * entry id → module source (for the optional sdk dry-run).
+ */
+export const buildManifest = (repoDir) => {
+  const cfg = readConfig(repoDir);
+  const results = [
+    ...listModules(repoDir, cfg.blocksDir).map((f) =>
+      entryOf("block", repoDir, cfg.blocksDir, f),
+    ),
+    ...listModules(repoDir, cfg.commandsDir).map((f) =>
+      entryOf("command", repoDir, cfg.commandsDir, f),
+    ),
+  ];
+  const problems = results.filter((r) => r.problems).map((r) => ({
+    file: r.file,
+    problems: r.problems,
+  }));
+  const entries = results.filter((r) => r.entry).map((r) => r.entry);
+
+  const dupes = [
+    ...new Set(
+      entries
+        .map((e) => e.id)
+        .filter((id, i, all) => all.indexOf(id) !== i),
+    ),
+  ];
+  if (dupes.length > 0)
+    problems.push({
+      file: "(catalog)",
+      problems: [`duplicate ids: ${dupes.join(", ")}`],
+    });
+
+  // The catalog must be dependency-CLOSED: every declared dependency
+  // resolves to a block entry in this same manifest.
+  const blockIds = new Set(
+    entries.filter((e) => e.kind === "block").map((e) => e.id),
+  );
+  const dangling = entries.flatMap((e) =>
+    e.dependencies
+      .filter((d) => !blockIds.has(d))
+      .map((d) => `${e.id} → ${d}`),
+  );
+  if (dangling.length > 0)
+    problems.push({
+      file: "(catalog)",
+      problems: [`dangling dependencies: ${dangling.join(", ")}`],
+    });
+
+  const sources = new Map(
+    results.filter((r) => r.entry).map((r) => [r.entry.id, r.source]),
+  );
+  return {
+    manifest: {
+      name: cfg.name,
+      owner: { name: cfg.owner },
+      entries,
+    },
+    sources,
+    problems,
+  };
+};
+
+export const manifestJson = (manifest) =>
+  JSON.stringify(manifest, null, 2) + "\n";
+
+export const MANIFEST_PATH = ".lineadraw/marketplace.json";
+
+/**
+ * Optional execution-level verification: dry-run every block through
+ * @lineadraw/sdk when the repo has it installed. Returns
+ * `{ ran, problems }` — `ran: false` when the sdk (or a new enough one) is
+ * absent; validation-only, so manifest CONTENT never depends on it.
+ */
+export const verifyWithSdk = async (repoDir, manifest, sources) => {
+  let sdk;
+  try {
+    const repoRequire = createRequire(join(repoDir, "package.json"));
+    sdk = await import(
+      pathToFileURL(repoRequire.resolve("@lineadraw/sdk")).href
+    );
+  } catch {
+    return { ran: false, problems: [] };
+  }
+  if (typeof sdk.testBlockDefinition !== "function")
+    return { ran: false, problems: [] }; // sdk predates module validation
+  const problems = [];
+  for (const entry of manifest.entries) {
+    if (entry.kind !== "block") continue; // commands are interactive — no dry run
+    const result = await sdk.testBlockDefinition(sources.get(entry.id));
+    if (!result.ok)
+      problems.push({ file: entry.source, problems: [result.error] });
+  }
+  return { ran: true, problems };
+};