@malloy-publisher/create-malloy-package 0.0.18 → 0.0.19

package/README.md

@@ -86,13 +86,13 @@ know it worked when the agent's first Malloy query returns data.
 ## Query it
 
 The web UI at http://localhost:4000 is the quickest look. For a check you can script,
-every model is queryable over REST at
-`POST /api/v0/environments/<env>/packages/<package>/models/<model>/query`. Run one of
-the starter model's views by name:
+a package's published models are queryable over REST at
+`POST /api/v0/environments/<env>/packages/<package>/models/<model>/query`. Address the
+package's surface, `index.malloy`, and run one of the starter model's views by name:
 
 ```bash
 curl -s -X POST \
-  http://localhost:4000/api/v0/environments/default/packages/sales/models/sales.malloy/query \
+  http://localhost:4000/api/v0/environments/default/packages/sales/models/index.malloy/query \
   -H 'Content-Type: application/json' \
   -d '{"sourceName": "sales", "queryName": "by_category", "compactJson": true}' \
   | jq -r .result
@@ -144,6 +144,10 @@ sales/                   the package
                          resolution differs from Publisher's (machine-specific
                          absolute path; drop it and open the editor at sales/ instead
                          if you commit the package)
+  index.malloy           the published surface: imports the model below and
+                         `export`s its source. What it exports is what Publisher
+                         lists and what may be queried, so no manifest key is
+                         needed; leave a source out to keep it internal
   sales.malloy           a starter model over the sample data
   data/sales.csv         the sample data
 ```

package/dist/index.js

@@ -666,6 +666,7 @@ function renderTemplate(name, vars) {
 }
 
 // src/scaffold.ts
+var INDEX_MODEL_NAME = "index.malloy";
 var MALLOY_AGENTS_FILE = "AGENTS.malloy.md";
 var BRIEFING_MARKER = "This directory is a [Malloy Publisher](https://github.com/malloydata/publisher)";
 var ENV_NAME = "default";
@@ -674,7 +675,7 @@ 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.6.0";
+var SERVER_VERSION = "0.7.0";
 function startCommandFor(envName) {
   return `npx -y @malloy-publisher/server@${SERVER_VERSION} --server_root . ` + `--config ./publisher.config.json --host ${BIND_HOST} ` + `--watch-env ${envName}`;
 }
@@ -771,7 +772,8 @@ function createPackage(options, result) {
     validateDataFile(options.dataFile);
   }
   const sourceName = toMalloyIdentifier(name);
-  const modelFile = `${sourceName}.malloy`;
+  const modelIsIndex = sourceName.toLowerCase() === "index";
+  const modelFile = modelIsIndex ? INDEX_MODEL_NAME : `${sourceName}.malloy`;
   const packageDir = path3.join(options.cwd, name);
   const packageDirExists = fs4.existsSync(packageDir);
   if (packageDirExists && !fs4.lstatSync(packageDir).isDirectory()) {
@@ -820,10 +822,14 @@ function createPackage(options, result) {
     dataPath = "data/sales.csv";
     writeFile(path3.join(packageDir, modelFile), renderTemplate("model.default.malloy", { sourceName }), options.cwd);
   }
+  if (!modelIsIndex) {
+    writeFile(path3.join(packageDir, INDEX_MODEL_NAME), renderTemplate(INDEX_MODEL_NAME, { sourceName, modelFile }), options.cwd);
+  }
   result.packageCreated = true;
   result.packageName = name;
   result.sourceName = sourceName;
   result.modelFile = modelFile;
+  result.indexFile = modelIsIndex ? modelFile : INDEX_MODEL_NAME;
   result.dataPath = dataPath;
   result.written.push(`${name}/`);
   if (packageDirExists) {
@@ -833,7 +839,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}/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.`;
+  return `--force does not empty the directory. It rewrites ${name}/publisher.json, ` + `${name}/malloy-config.json, ${name}/${modelFile}, ` + (modelFile === INDEX_MODEL_NAME ? `` : `${name}/${INDEX_MODEL_NAME} `) + `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";
@@ -1408,7 +1414,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"}'`, "```", "", `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.`, "");
+    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.`, "", result.indexFile === result.modelFile ? `That file is also \`${result.indexFile}\`, this package's published surface: what it \`export\`s is what Publisher lists and what may be queried. Query through it.` : `\`${result.packageName}/${result.indexFile}\` is the package's published surface: it imports that model and \`export\`s \`${result.sourceName}\`. Publisher lists and accepts queries against the surface, so address queries to \`${result.indexFile}\`, not to \`${result.modelFile}\` -- a model off the surface is refused with a 404. Add a source to the \`export\` list to publish it.`, "", `One thing that surface cannot publish: a dashboard. A \`dashboards/*.malloy\` file is a file, not a source, so \`${result.indexFile}\` has no way to \`export\` it, and a dashboard added to this package is NOT served -- it is written, it compiles, and it is withheld with a load warning. To serve dashboards, declare an \`explores\` in \`publisher.json\` naming \`${result.indexFile}\` and every dashboard file; the explicit key overrides the convention. Decide that before building one, because the fix is a different curation shape rather than an extra line.`, "", `The package's REST base is:`, "", "```", base, "```", "", "Run one of its views from a script:", "", "```bash", `curl -s -X POST ${base}/models/${result.indexFile}/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), "");

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.18",
+   "version": "0.0.19",
    "license": "MIT",
    "type": "module",
    "engines": {
@@ -45,7 +45,7 @@
       "test:e2e": "bun test --timeout 180000 ./tests/e2e"
    },
    "dependencies": {
-      "@malloy-publisher/skills": "^0.1.22",
+      "@malloy-publisher/skills": "^0.1.23",
       "commander": "^12.1.0"
    },
    "devDependencies": {

package/templates/AGENTS.md

@@ -154,8 +154,13 @@ watch-mode recompile that failed), and
 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
+REST, for a script or a check that does not need an agent: a model on the package's
+published surface is queryable at
+`POST /api/v0/environments/<env>/packages/<package>/models/<model>/query`. Not every
+`.malloy` file on disk is: where the package has a root `index.malloy`, that file is the
+surface, and a model it does not export is refused with a 404 that reads the same as a
+model that does not exist. Address queries to the surface file, and take the model names
+from the package listing below rather than from the filenames. After a
 model-file edit `GET /api/v0/environments/<env>/packages/<package>?reload=true` recompiles
 the package and comes back 424 with the compile errors when it does not compile. Any other
 non-2xx is a failed check too, and its `message` says what went wrong: a 404 for a package

package/templates/index.malloy

@@ -0,0 +1,20 @@
+// index.malloy: this package's published surface.
+//
+// Publisher reads a package's index.malloy as the list of what it publishes,
+// so publisher.json needs no "explores" key: the surface is whatever this
+// file exports.
+//
+// `export { ... }` is the curation, and it is a real boundary rather than
+// just a listing filter. A source named here is discoverable AND queryable.
+// A source left out still compiles, and other models can import, join and
+// extend it, but a direct query against it is refused with a 404 --
+// indistinguishable from a source that does not exist. Add a name here to
+// publish it; leave one out to keep it as an internal building block.
+//
+// To curate listings WITHOUT refusing queries, keep an explicit "explores" in
+// publisher.json alongside "queryableSources": "all". That is the one thing
+// this file cannot express. See docs/discovery-and-access.md.
+
+import "{{modelFile}}"
+
+export { {{sourceName}} }

package/templates/model.custom.xlsx.malloy

@@ -17,7 +17,9 @@
 //
 // STEP 1: look at the sheet, because the fix needs three things this file cannot
 // tell you: which sheet, which row the header is on, and which column marks a
-// real row. Add this to the bottom of THIS FILE, reload the package, then run
+// real row. Add the probe source below to `index.malloy` -- NOT to this file --
+// and add `{{sourceName}}_probe` to the `export { ... }` line already there.
+// Reload the package, then query `index.malloy` and run
 // `{{sourceName}}_probe -> peek`. Delete it once you have what you need.
 //
 //   source: {{sourceName}}_probe is duckdb.sql("""
@@ -29,9 +31,18 @@
 //     view: peek is { select: *; limit: 25 }
 //   }
 //
-// It has to go in the file rather than being sent as a one-off query: Publisher
-// refuses raw SQL in an ad-hoc query ("`duckdb.sql(...)` cannot be used in a
-// restricted query"), and only allows it where it is part of a model.
+//   export { {{sourceName}}, {{sourceName}}_probe }   -- the existing line, probe added
+//
+// Two reasons it goes there and not here. Raw SQL has to be part of a model at
+// all: Publisher refuses it in an ad-hoc query ("`duckdb.sql(...)` cannot be
+// used in a restricted query"). And `index.malloy` is this package's published
+// surface, so it is the only model a query can be addressed to -- a query
+// against this file is refused with a 404, and a source this package does not
+// export is refused even when the query goes to the right file. Putting the
+// probe in `index.malloy` and naming it in `export { ... }` satisfies both.
+// Edit the export line that is already there rather than adding a second one:
+// Malloy refuses a name that two export statements both list. Take the probe
+// back out of that line when you delete it.
 //
 // `peek` prints the first 25 rows exactly as they sit in the sheet, banner rows
 // and all, so you can count down to the real header row and see which column
@@ -76,7 +87,8 @@
 //   }
 //
 // Then reload the package, check the reload itself came back OK, and only then
-// run `overview` again. A reload that fails to compile leaves the previously
+// run `overview` again -- addressed to `index.malloy`, like every query against
+// this package. A reload that fails to compile leaves the previously
 // compiled model serving, so `overview` answers 200 with the OLD number and it
 // looks as though your edit did nothing. The reason is in the reload response,
 // not in the query.