Malloy Publish

<!--
Copyright (c) Credible Data Inc.
SPDX-License-Identifier: MIT
-->

Packaging Malloy models for Publisher

CRITICAL: Only package or prepare a release when the user explicitly asks. Making model changes, adding documentation, or building notebooks is NOT a publish request. Never auto-package after completing other tasks.

Publishing in open-source Publisher

Automated publishing is not part of the open-source Malloy Publisher tool surface yet. There is no publish tool to call from this skill. What this skill does is get a package into a publishable shape: a valid publisher.json, a flat layout, and the right files in the package root.

Once the package is in shape, self-hosters publish it through their own host: commit the package to git, then run the host's publish path (for example, the deploy step that points a Publisher server at the package directory or repository). The mechanics of that path depend on how the Publisher instance is deployed, so confirm with the user how their instance is served rather than assuming a hosted control plane.

Prerequisites

• Malloy model (.malloy) and/or notebook (notebooks/<slug>.malloy) files ready
• The Publisher MCP tools configured (used by the modeling and analysis skills, not by a publish step)

Connections: a flat-file package needs none

A package backed by data files (CSV/Parquet/XLSX/JSON) needs no connections entry at all in publisher.config.json: every loaded package automatically gets its own DuckDB sandbox connection named duckdb, which is what duckdb.table('data/file.csv') resolves against. That name is reserved: declaring an environment-level connection named duckdb fails the whole environment at init (name an env-level DuckDB connection something like shared_duckdb instead). See docs/connections.md.

Two more facts about how a Publisher server sees the package, both easy to get wrong:

• A package location is treated as local only when it starts with ./, ../, ~/, or /. A bare name like "spotify" is silently not local; write "./spotify".

• Local authoring means --watch-env. Without --watch-env <env>, Publisher copies each local package into publisher_data/ at boot and serves the copy; edits to your source directory are never read, however many times you save. Start the server with --watch-env <env> (mounts the package in place and live-reloads), the same command skill:malloy-html-data-apps uses:

  npx @malloy-publisher/server --server_root . --port 4000 --watch-env <env>

Step 1: Verify publisher.json

Check if publisher.json exists in the package root. If it does, proceed to Step 2.

If it doesn't exist, create one. Suggest a package name based on the model content, write a brief description, and default to version 0.0.1.

{
  "name": "package-name",
  "version": "0.0.1",
  "description": "Brief description of the package"
}

Naming conventions:

• name: lowercase, hyphens allowed (e.g., ecommerce, sales-analytics)
• version: semver format (e.g., 0.0.1, 1.2.3)

Curating discovery & the query boundary (optional)

A package with no index.malloy and no explores exposes everything: every model is listed and every source is directly queryable.

To curate, add an index.malloy at the package root. Publisher reads it as the package's published surface, so no manifest field is involved:

// index.malloy
import "order_analysis.malloy"
import "staging.malloy"

export { orders, customers }

What it exports is what agents discover and what may be queried. Everything else still compiles, and other models can import, join and extend it, but a direct query against it is refused with a 404. Where nothing in the model is gated, the 404 says the source is off the surface and how to publish it; where a gate is in play, it reads exactly like a source that does not exist. Reach for this when you have raw/staging/scaffolding sources that exist to build a curated entry point and you don't want agents landing on, or querying, them directly.

Address queries to the surface. Once a package has an index.malloy, .../models/staging.malloy/query is no longer a query entry point, even for a source that file declares itself. Use .../models/index.malloy/query. If you are debugging a refusal rather than authoring, skill:malloy-source-unreachable covers the three ways a source can be out of reach and how to tell them apart.

A surface can be layered. An index.malloy may front a file that fronts another. A source re-exported through a chain of files stays queryable through the surface at any depth, because admission follows the declaration rather than the path taken to it.

Curation hides a landing point, not a column. A published source may join an unpublished one, and a query grouping by a joined field returns that field's values normally. If a column must not be readable, do not join it into something you publish; gate it with #(authorize) instead.

Leaving a source out does not put it out of reach, but there is a condition. export { ... } also decides what an importing file may see, which is Malloy's rule rather than Publisher's. A file that declares no export hands an importer everything it declares, so an unpublished source stays importable and joinable from the file that declares it. A file that does declare one hands over exactly that list: importing a file whose export omits a source and then naming it fails to compile with Reference to undefined object. Put an export on a mid-layer file only when you mean to narrow what its importers can build on, not just what Publisher lists.

About export { … }: the surface filters which files are listed; export { … } (a Malloy statement) filters which sources within a file are exposed, and the two compose. You usually don't write it in a leaf model: a file with no export exposes all of its own top-level sources. It must appear after the definitions it names. See Malloy: Imports & Exports.

Givens reach callers through index.malloy's imports, not its export. A given: is a name like a source. A caller can set it only if index.malloy has it in scope, and you never list givens in export { … }. How you import decides it:

• import "orders.malloy" (the whole file) brings every given orders.malloy declares. Use this form, then export only the curated sources.
• import { orders } from "orders.malloy" brings only orders. Its givens stay behind. Name them too: import { orders, REGION } from "orders.malloy".
• Imports don't chain. If orders.malloy gets its givens from a givens.malloy, import givens.malloy into index.malloy as well, or list the givens in orders.malloy's own export { … }.

A given index.malloy leaves out fails in one of three ways, depending on how it is declared:

To check, fetch index.malloy's model: its givens should list every given a published source reads.