@malloy-publisher/create-malloy-package 0.0.5 → 0.0.7

package/README.md

@@ -135,6 +135,10 @@ CLAUDE.md / AGENTS.md    short, package-scoped agent instructions
 .claude/skills/          the Malloy agent skills, copied in as real files
 sales/                   the package
   publisher.json         the manifest
+  malloy-config.json     for the VS Code/Cursor Malloy extension, whose relative-path
+                         resolution differs from Publisher's (machine-specific
+                         absolute path; drop it and open the editor at sales/ instead
+                         if you commit the package)
   sales.malloy           a starter model over the sample data
   data/sales.csv         the sample data
 ```
@@ -361,17 +365,32 @@ package's built-in DuckDB sandbox, so no database credentials are required.
 
 ### The workspace path
 
-Create the workspace somewhere whose full path is made only of letters, digits, `-`,
-`_`, `.` and `/`. DuckDB cannot read a data file under a path containing a space, a
-parenthesis, an apostrophe, or any non-ASCII character, and Publisher resolves the
-model's relative table path against the workspace directory before that check runs. So
-a single space anywhere above the package makes every model in it fail to load, with
-the server still reporting healthy and the only visible symptom an empty package list.
-
-Common directories that trip it: `~/Documents/My Projects`, `~/Google Drive`,
-`~/OneDrive - Company`, and any home directory whose username carries an accent. The
-scaffolder checks this before writing anything and refuses to run in such a directory,
-naming the offending character. Move to a path like `~/malloy-workspace` and run again.
+Spaces, apostrophes, and quotes in the workspace path are fine for querying data: the
+model's data references are relative (`data/sales.csv`) and Publisher's per-package
+DuckDB sandbox resolves them against the package's working directory, so the workspace
+path never reaches DuckDB's path parser on that path. `~/Documents/My Projects`,
+`~/Google Drive`, `~/OneDrive - Company`, and a `2026-08-13 Project Name` directory all
+work — verified end-to-end (load and query a CSV) under paths containing a space, an
+apostrophe, and a double quote. An earlier version of this tool refused all of them on a
+premise that does not hold against the current server.
+
+One server code path is an exception: the databases endpoint's schema probe builds an
+absolute path literal and does reach the path parser, so a spaced/quoted workspace path
+still loses row counts and column types there (the package still loads and queries
+correctly). Pre-existing server behavior, tracked separately — not a reason to avoid
+these paths.
+
+What is refused is a path outside **printable ASCII** — an accent, an emoji, any
+non-ASCII character, and every control character. This is the server's own rule, not
+DuckDB's: Publisher checks an environment path against `[\x20-\x7E]` before mounting a
+package from it, so a workspace under `~/josé` loads nothing. The server still reports
+`serving`, with the environment missing and the reason only in the `loadErrors` of
+`/api/v0/status`, so the scaffolder refuses up front instead — before anything is
+written, naming the character. Control characters are refused for the additional reason
+that they corrupt the commands and briefing files the scaffold writes verbatim.
+
+So a home directory whose username carries an accent needs the workspace somewhere
+else, such as `~/malloy-workspace`.
 
 ## License
 

package/dist/index.js

@@ -246,6 +246,27 @@ function toMalloyIdentifier(name) {
   return identifier;
 }
 
+// src/node_version.ts
+var MIN_NODE_MAJOR = 20;
+var REQUIRED_NODE_RANGE = `>=${MIN_NODE_MAJOR}`;
+function nodeVersionWarning(versions) {
+  if (versions.bunVersion) {
+    return;
+  }
+  const match = /^v?(\d+)\./.exec(versions.nodeVersion.trim());
+  if (!match || Number(match[1]) >= MIN_NODE_MAJOR) {
+    return;
+  }
+  return [
+    `! Node.js ${MIN_NODE_MAJOR} or newer is required to run Publisher. This shell is running Node.js ${versions.nodeVersion}.`,
+    `  The workspace is scaffolded and correct, but Publisher will not work on this Node:`,
+    `  upgrade before running npm start.`,
+    `    nvm:  nvm install ${MIN_NODE_MAJOR} && nvm use ${MIN_NODE_MAJOR}`,
+    `    mise: mise use -g node@${MIN_NODE_MAJOR}   then open a new shell`
+  ].join(`
+`);
+}
+
 // src/registry_check.ts
 import * as http from "node:http";
 import * as https from "node:https";
@@ -644,14 +665,26 @@ var MCP_PORT = 4040;
 var ALT_PUBLISHER_PORT = PUBLISHER_PORT + 100;
 var ALT_MCP_PORT = MCP_PORT + 100;
 var BIND_HOST = "127.0.0.1";
-var SERVER_VERSION = "0.0.234";
+var SERVER_VERSION = "0.0.244";
 function startCommandFor(envName) {
   return `npx -y @malloy-publisher/server@${SERVER_VERSION} --server_root . ` + `--config ./publisher.config.json --host ${BIND_HOST} ` + `--watch-env ${envName}`;
 }
 function resetCommandFor(envName) {
   return `${startCommandFor(envName)} --init`;
 }
-var DUCKDB_SAFE_PATH_CHAR = /[A-Za-z0-9._~:/?#@!$&*+,=%-]/;
+function portOverrideCommandFor(result) {
+  return withAlternatePorts(result.hasStartScript ? "npm start" : result.startCommand, result.hasStartScript);
+}
+function resetPortOverrideCommandFor(result) {
+  return withAlternatePorts(result.hasResetScript ? "npm run reset" : result.resetCommand, result.hasResetScript);
+}
+function withAlternatePorts(command, viaNpmScript) {
+  return `${command}${viaNpmScript ? " --" : ""} ` + `--port ${ALT_PUBLISHER_PORT} --mcp_port ${ALT_MCP_PORT}`;
+}
+function isServablePathCharacter(character) {
+  const codePoint = character.codePointAt(0);
+  return codePoint >= 32 && codePoint <= 126;
+}
 var RESERVED_PACKAGE_NAMES = new Set([
   "AGENTS.md",
   MALLOY_AGENTS_FILE,
@@ -749,6 +782,15 @@ function createPackage(options, result) {
   assertWithinWorkspace(dataDir, options.cwd, `${name}/data`);
   fs4.mkdirSync(dataDir, { recursive: true });
   writeFile(path3.join(packageDir, "publisher.json"), JSON.stringify({ name }, null, 2) + `
+`, options.cwd);
+  writeFile(path3.join(packageDir, "malloy-config.json"), JSON.stringify({
+    connections: {
+      duckdb: {
+        is: "duckdb",
+        workingDirectory: path3.resolve(packageDir)
+      }
+    }
+  }, null, 2) + `
 `, options.cwd);
   let dataPath;
   if (options.dataFile !== undefined) {
@@ -782,7 +824,7 @@ function createPackage(options, result) {
 function forceDescription(name, modelFile, host) {
   const agentFiles = host === "cursor" ? "AGENTS.md" : "AGENTS.md and CLAUDE.md";
   const mcpPath = mcpConfigPathFor(host);
-  return `--force does not empty the directory. It rewrites ${name}/publisher.json, ` + `${name}/${modelFile} and the data file it copies into ${name}/data/, and ` + `leaves anything else in there alone. It also refreshes .claude/skills/ ` + `from the bundled copies, as every run does. Outside the package it ` + `replaces ${agentFiles}; in package.json it sets only the "start" and ` + `"reset" scripts and keeps the rest of the file as it is; in ${mcpPath} it ` + `sets only the "malloy" server and keeps the others. publisher.config.json ` + `is extended, never rewritten, and .gitignore only gains the lines it is ` + `missing, with or without --force. None of those merges is a rewrite even ` + `when the file cannot be read: a package.json that is not valid JSON aborts ` + `the run before anything is written, and an unreadable ${mcpPath} or ` + `.gitignore is left alone and reported. If this directory has an AGENTS.md ` + `of its own, --force is not what you want for it: a run without --force ` + `keeps that file and writes the Publisher briefing to ${MALLOY_AGENTS_FILE} ` + `beside it instead, regenerating that one on every run.`;
+  return `--force does not empty the directory. It rewrites ${name}/publisher.json, ` + `${name}/malloy-config.json, ${name}/${modelFile} and the data file it ` + `copies into ${name}/data/, and leaves anything else in there alone. ` + `It also refreshes .claude/skills/ ` + `from the bundled copies, as every run does. Outside the package it ` + `replaces ${agentFiles}; in package.json it sets only the "start" and ` + `"reset" scripts and keeps the rest of the file as it is; in ${mcpPath} it ` + `sets only the "malloy" server and keeps the others. publisher.config.json ` + `is extended, never rewritten, and .gitignore only gains the lines it is ` + `missing, with or without --force. None of those merges is a rewrite even ` + `when the file cannot be read: a package.json that is not valid JSON aborts ` + `the run before anything is written, and an unreadable ${mcpPath} or ` + `.gitignore is left alone and reported. If this directory has an AGENTS.md ` + `of its own, --force is not what you want for it: a run without --force ` + `keeps that file and writes the Publisher briefing to ${MALLOY_AGENTS_FILE} ` + `beside it instead, regenerating that one on every run.`;
 }
 function mcpConfigPathFor(host) {
   return host === "cursor" ? ".cursor/mcp.json" : ".mcp.json";
@@ -886,24 +928,23 @@ function installWorkspaceSkills(cwd, result) {
 }
 function assertServablePath(cwd) {
   const absolute = path3.resolve(cwd);
-  const candidate = path3.sep === "\\" ? absolute.replace(/\\/g, "/") : absolute;
-  for (const character of candidate) {
-    if (!DUCKDB_SAFE_PATH_CHAR.test(character)) {
-      throw new ScaffoldError(`This workspace cannot live in ${printable(absolute)}: DuckDB ` + `cannot read a ` + `data file under a path containing ${describeCharacter(character)}, so every model here would fail to load with the server ` + `still reporting healthy. Move to a path made of letters, ` + `digits, "-", "_", "." and "/" (for example ` + `~/malloy-workspace) and run again.`);
+  for (const character of absolute) {
+    if (!isServablePathCharacter(character)) {
+      const codePoint = character.codePointAt(0);
+      const consequence = codePoint < 32 || codePoint === 127 ? `which would corrupt the commands and briefing files this ` + `tool writes verbatim` : `and Publisher refuses to mount a package from a path ` + `outside printable ASCII: it would report serving with this ` + `workspace's environment missing, naming the reason only in ` + `/api/v0/status loadErrors`;
+      throw new ScaffoldError(`This workspace cannot live in ${printable(absolute)}: its path ` + `contains ${describeCharacter(character)}, ${consequence}. ` + `Move to a path of printable ASCII and run again — spaces are ` + `fine, so ~/Documents/My Projects works.`);
     }
   }
 }
 function describeCharacter(character) {
   const named = {
-    " ": "a space",
-    "'": "an apostrophe",
-    '"': "a double quote",
-    "\\": "a backslash",
-    "\t": "a tab"
+    "\t": "a tab",
+    "\n": "a line feed",
+    "\r": "a carriage return"
   };
-  const label = named[character] ?? `"${character}"`;
+  const label = named[character] ?? `"${printable(character)}"`;
   const codePoint = character.codePointAt(0);
-  return codePoint < 32 || codePoint > 126 ? `${label} (U+${codePoint.toString(16).toUpperCase().padStart(4, "0")})` : label;
+  return `${label} (U+${codePoint.toString(16).toUpperCase().padStart(4, "0")})`;
 }
 function assertWorkspacePathsContained(options, mcpConfigPath) {
   const relatives = [
@@ -1326,7 +1367,7 @@ function renderAgentsFile(result, host, envPackages) {
   const skillsCount = String(result.skillsInstalled);
   const skillsNote = result.skillsInstalled === 0 ? "This run installed no skills into `.claude/skills/` (the scaffolder's output says why), so there are none here to load. Pull the same guidance as MCP prompts from the endpoint above instead." : host === "cursor" ? `\`.claude/skills/\` holds ${skillsCount} Malloy agent skills as real files. Cursor reads \`AGENTS.md\`; these skills are the same guidance broken out by task, and any MCP client can also pull them as prompts from the endpoint above.` : `\`.claude/skills/\` holds ${skillsCount} Malloy agent skills as real files, so Claude Code auto-discovers them. Hosts that read \`AGENTS.md\` rather than Anthropic Agent Skills can pull the same guidance as MCP prompts from the endpoint above.`;
   const startCommand = result.hasStartScript ? "npm start" : result.startCommand;
-  const portOverrideCommand = `${startCommand}${result.hasStartScript ? " --" : ""} ` + `--port ${ALT_PUBLISHER_PORT} --mcp_port ${ALT_MCP_PORT}`;
+  const portOverrideCommand = portOverrideCommandFor(result);
   return renderTemplate("AGENTS.md", {
     title: result.packageCreated ? `${result.packageName}: a Malloy Publisher package` : "A Malloy Publisher workspace",
     startCommand,
@@ -1357,7 +1398,7 @@ function packageSection(result, envPackages) {
   ];
   if (result.packageCreated) {
     const base = restBase(result.packageName);
-    lines.push(`\`${result.packageName}/${result.modelFile}\` defines a Malloy source named \`${result.sourceName}\` over local data. Read it for the real source, field, and view names and use them verbatim; never guess them. The package's REST base is:`, "", "```", base, "```", "", "Run one of its views from a script:", "", "```bash", `curl -s -X POST ${base}/models/${result.modelFile}/query \\`, "  -H 'content-type: application/json' \\", `  -d '{"query":"run: ${result.sourceName} -> overview"}'`, "```", "");
+    lines.push(`\`${result.packageName}/${result.modelFile}\` defines a Malloy source named \`${result.sourceName}\` over local data. Read it for the real source, field, and view names and use them verbatim; never guess them. The package's REST base is:`, "", "```", base, "```", "", "Run one of its views from a script:", "", "```bash", `curl -s -X POST ${base}/models/${result.modelFile}/query \\`, "  -H 'content-type: application/json' \\", `  -d '{"query":"run: ${result.sourceName} -> overview"}'`, "```", "", `The VS Code / Cursor Malloy extension resolves the model's relative \`duckdb.table('data/…')\` paths against the EDITOR WORKSPACE root, while Publisher resolves them against the package directory. \`${result.packageName}/malloy-config.json\` (generated, machine-specific absolute path) bridges that for an editor opened at this workspace root; without it, open the editor at \`${result.packageName}/\` itself, or a model Publisher serves fine shows unresolved-table errors in the editor.`, "");
   }
   if (others.length > 0) {
     lines.push(otherPackagesParagraph(result, others, restBase), "");
@@ -1385,6 +1426,9 @@ function workspacePackageJson(cwd, result) {
     name: toNpmName(path3.basename(path3.resolve(cwd))),
     version: "0.1.0",
     private: true,
+    engines: {
+      node: REQUIRED_NODE_RANGE
+    },
     scripts: {
       start: result.startCommand,
       reset: result.resetCommand
@@ -1399,7 +1443,8 @@ function workspaceGitignoreEntries() {
     "publisher_data/",
     "publisher.db*",
     "*.log",
-    ".DS_Store"
+    ".DS_Store",
+    "malloy-config.json"
   ];
 }
 function workspaceGitignore() {
@@ -1565,6 +1610,15 @@ async function run(name, options) {
     if (warning) {
       process.stdout.write(`
 ${yellow(warning)}
+`);
+    }
+    const nodeWarning = nodeVersionWarning({
+      nodeVersion: process.version,
+      bunVersion: process.versions.bun
+    });
+    if (nodeWarning) {
+      process.stdout.write(`
+${yellow(nodeWarning)}
 `);
     }
   } catch (err) {
@@ -1951,6 +2005,12 @@ function formatSuccess(result) {
   if (!result.hasStartScript) {
     lines.push(...exposureWarning("npm start", result.declinedStartScript));
   }
+  lines.push(dim(`  If port ${result.publisherPort} is taken by a Publisher serving a ` + `DIFFERENT
+  workspace, boot with
+` + `  ${result.needsReset ? resetPortOverrideCommandFor(result) : portOverrideCommandFor(result)}
+` + `  and edit the url in ${result.mcpConfigPath} to the new MCP port.` + (result.needsReset ? "" : `
+  One already serving THIS workspace is the other case: ` + `stop it,
+  because the lock is on the workspace, not the ` + `port.`)));
   lines.push(`  ${cyan(url)}   ${dim("explore in the browser")}`);
   lines.push("");
   lines.push(bold("Check it is ready:"));

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/create-malloy-package",
    "description": "Scaffold a Malloy Publisher package and a local agent workspace, so one command takes you from nothing to an agent that can query your data.",
-   "version": "0.0.5",
+   "version": "0.0.7",
    "license": "MIT",
    "type": "module",
    "engines": {
@@ -45,12 +45,12 @@
       "test:e2e": "bun test --timeout 180000 tests/e2e"
    },
    "dependencies": {
-      "@malloy-publisher/skills": "^0.1.3",
+      "@malloy-publisher/skills": "^0.1.4",
       "commander": "^12.1.0"
    },
    "devDependencies": {
       "@eslint/js": "^8.57.0",
-      "@malloydata/malloy": "^0.0.426",
+      "@malloydata/malloy": "^0.0.427",
       "@modelcontextprotocol/sdk": "^1.13.2",
       "@types/bun": "^1.2.21",
       "@types/node": "^24.10.0",

package/templates/AGENTS.md

@@ -143,7 +143,9 @@ against the model, so it takes the snippet as a required `source` argument; it r
 the model file's own errors too),
 `malloy_reloadPackage` (pick up on-disk model edits with no restart, and surface a
 watch-mode recompile that failed), and
-`malloy_searchDocs`. {{mcpNote}}
+`malloy_searchDocs`, and `malloy_searchDatabaseSchema` (find the tables in a database
+connection by plain-English description, for modelling data that is not in this package
+yet; it returns each table's columns and the `source:` line to start from). {{mcpNote}}
 
 REST, for a script or a check that does not need an agent: every model is queryable at
 `POST /api/v0/environments/<env>/packages/<package>/models/<model>/query`, and after a