@exor404/mdslides 0.1.0 → 0.1.3

package/README.md

@@ -12,32 +12,78 @@ dev server or builds a self-contained `dist/` you can host anywhere static.
 ## Quick start
 
 ```bash
-mdslides ./chemistry          # scaffolds a project, then presents it
+npx @exor404/mdslides@latest
 ```
 
-Point `mdslides` at a folder and it scaffolds a project: it **asks for a
-name**, writes `<name>.md` (e.g. `chemistry.md`) with three sample slides — a
-title page, a list, and a help slide — plus a `mdslides.config.js`, then opens
-the dev server. The name defaults to the folder, so pressing Enter at
-`Name your presentation (chemistry):` gives you `chemistry/chemistry.md`. That
-file *is* your deck — edit it and the slides live-reload.
+No install step. It **asks for a name**, scaffolds `<name>/<name>.md` (three
+sample slides — a title page, a list, and a help slide) plus a
+`mdslides.config.js`, and opens the dev server. The name defaults to the current
+folder, so pressing Enter at `Name your presentation (chemistry):` gives you
+`chemistry/chemistry.md`. That file *is* your deck — edit it and the slides
+live-reload.
+
+Point it at a folder for the other commands:
 
 ```bash
-mdslides ./chemistry          # present (dev server, live-reload)
-mdslides build ./chemistry    # static build → ./chemistry/dist/
-mdslides preview ./chemistry  # serve the built dist/
-mdslides export ./chemistry   # → chemistry.pdf (one page per slide)
+npx @exor404/mdslides ./chemistry          # present (dev server, live-reload)
+npx @exor404/mdslides build ./chemistry    # static build → ./chemistry/dist/
+npx @exor404/mdslides preview ./chemistry  # serve the built dist/
+npx @exor404/mdslides export ./chemistry   # → chemistry.pdf (one page per slide)
 ```
 
-Already have a deck? Point straight at the file: `mdslides ./chemistry.md`.
+Already have a deck? Point straight at the file: `npx @exor404/mdslides ./chemistry.md`.
+
+> **Heads-up:** `npm install @exor404/mdslides` only *installs* the package —
+> running the CLI (via `npx`, as above) is what scaffolds and presents. Using
+> `npx` also keeps the engine's dependencies in npx's cache instead of bloating
+> a project's `node_modules`.
 
-Try the bundled example:
+Prefer a global command? `npm i -g @exor404/mdslides` makes `mdslides` available
+directly (`mdslides ./chemistry`).
+
+Try the bundled example from a clone:
 
 ```bash
 npm install
 npm run dev        # opens ./example
 ```
 
+## Install
+
+The package is published on the public npm registry as
+[`@exor404/mdslides`](https://www.npmjs.com/package/@exor404/mdslides). Pick the
+option that suits you:
+
+**No install (recommended).** `npx` fetches and caches the latest version, then
+runs it — nothing is added to your project:
+
+```bash
+npx @exor404/mdslides@latest          # prompts for a name, scaffolds + presents
+```
+
+**Global install.** Puts an `mdslides` command on your `PATH`:
+
+```bash
+npm install -g @exor404/mdslides
+mdslides ./chemistry                  # then use it anywhere
+mdslides --help                       # (or run with no folder to start fresh)
+```
+
+Update later with `npm update -g @exor404/mdslides`; remove with
+`npm uninstall -g @exor404/mdslides`.
+
+**As a project dependency.** Add it to a repo so collaborators get the same
+version via `npm install`:
+
+```bash
+npm install -D @exor404/mdslides
+npx mdslides ./chemistry              # resolves from local node_modules
+```
+
+> Requires **Node 18+**. Installing the package pulls in its rendering engine
+> (Astro, Shiki, KaTeX) — that's why `npx` is the lightest way to try it: those
+> dependencies stay in npx's cache instead of your project's `node_modules`.
+
 ## The deck model
 
 **One markdown file is the whole deck.** Every `#` (H1) heading starts a new
@@ -147,33 +193,66 @@ fragments shown). It uses [Playwright](https://playwright.dev) if installed
 Releases go to the **public npm registry** (npmjs.com), so anyone can
 `npx @exor404/mdslides`. A tag-triggered GitHub Actions pipeline
 ([`.github/workflows/package-publish.yml`](.github/workflows/package-publish.yml))
-publishes via **OIDC Trusted Publishing** — GitHub mints a one-time identity
-token for the run, so **no npm token or secret is ever stored**.
+does the publishing for you: it runs **only when you push a `v*` tag**, verifies
+the tag matches `package.json`, and runs `npm publish` against npmjs.com using an
+automation token stored as the `NPM_TOKEN` repository secret.
 
-**One-time setup** (needed once, because Trusted Publishing attaches to an
-existing package):
+### How the pipeline works
 
-```bash
-npm login                       # browser sign-in to npmjs.com
-npm publish --access public     # publish the first version by hand
 ```
+push tag v0.1.3 ──► GitHub Actions ──► checkout ──► setup Node 22
+                                          │
+                                          ├─ guard: tag (v0.1.3) must equal
+                                          │   package.json "version" (0.1.3),
+                                          │   else the run fails
+                                          │
+                                          └─ npm publish  (auth: NPM_TOKEN)
+                                                  └──► npmjs.com
+```
+
+The version guard means the git tag and the published version can never drift —
+if they disagree, the run stops before publishing.
 
-Then on npmjs.com open the package → **Settings → Trusted Publisher → GitHub
-Actions** and register:
+### One-time setup
 
-- **Repository:** `eXor404/mdslides`
-- **Workflow filename:** `package-publish.yml`
+You only do this once. It wires an npm token into the repo so Actions can publish
+on your behalf.
 
-After that, every release is automatic:
+1. **Create an npm automation token.** On npmjs.com: avatar → **Access Tokens** →
+   **Generate New Token** → **Automation** (or a **Granular** token scoped to the
+   `@exor404/mdslides` package with **Read and write**). Copy the value — npm
+   shows it only once.
+2. **Add it to GitHub as a secret.** Repo → **Settings** → **Secrets and
+   variables** → **Actions** → **New repository secret**. Name it exactly
+   `NPM_TOKEN`, paste the token, **Add secret**. (It's a *secret*, not a
+   *variable* — secrets are encrypted and hidden from logs.)
+
+> The very first version must exist on npm before automation can update it.
+> If the package isn't published yet, do one manual publish first:
+> `npm login && npm publish --access public`.
+
+### Cutting a release
+
+Once the secret is in place, every release is three commands:
 
 ```bash
-npm version patch          # bumps package.json (0.1.0 → 0.1.1) and tags v0.1.1
+npm version patch          # bumps package.json (0.1.2 → 0.1.3) and commits + tags v0.1.3
 git push origin main       # push the version-bump commit
-git push origin v0.1.1     # push the tag → the pipeline publishes, tokenlessly
+git push origin v0.1.3     # push the tag → the pipeline publishes
 ```
 
-`npm version` creates the matching `vX.Y.Z` tag for you. The workflow refuses
-to publish if the tag and `package.json` version disagree, so they can't drift.
+`npm version patch` (or `minor` / `major`) bumps `package.json`, makes the commit,
+and creates the matching `vX.Y.Z` tag in one step. Pushing that tag is what
+triggers the workflow. Watch it run under the repo's **Actions** tab; when it goes
+green the new version is live on npm.
+
+**Prefer to bump by hand?** Edit `"version"` in `package.json`, then:
+
+```bash
+git commit -am "🔖 Release 0.1.3"
+git tag v0.1.3             # must match package.json exactly, or the guard fails
+git push && git push --tags
+```
 
 ## Requirements
 

package/app/integrations/mdslides-assets.js

@@ -23,7 +23,15 @@ const MIME = {
 };
 
 const EXCLUDED_TOP = new Set(['dist', 'node_modules', '.git', '.astro', '.vscode', '.idea']);
-const EXCLUDED_FILES = new Set(['mdslides.config.js']);
+const EXCLUDED_FILES = new Set([
+  'mdslides.config.js',
+  // Project scaffolding that lives alongside the deck (npm create … layout) —
+  // never part of the presentation, so keep it out of the built dist/.
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+]);
 
 function isExcludedRel(rel) {
   if (!rel || rel === '.' || rel === '..') return true;

package/bin/cli.js

@@ -60,7 +60,10 @@ function parseArgs(argv) {
     }
   }
 
-  if (!file) {
+  // No target + the default `dev` command → start a brand-new project: we'll
+  // prompt for a name and scaffold it. Any other command needs an explicit
+  // target (there's nothing to build/preview/export yet).
+  if (!file && cmd !== 'dev') {
     fail('Missing target.\nUsage: mdslides [dev|build|preview|export] [--theme <name>] <folder|file.md>');
   }
 
@@ -130,6 +133,21 @@ async function scaffoldProject(dir) {
   return scaffoldDeck(resolve(dir, `${stem}.md`));
 }
 
+// Start a project from scratch when `mdslides` is run with no target (e.g.
+// `npx @exor404/mdslides`): ask for a name, then create `<name>/<name>.md` in
+// the current directory and present it. No install or extra command needed.
+async function scaffoldNewProject() {
+  const fallback = slugify(basename(process.cwd())) || 'presentation';
+  const answer = await ask(`Name your presentation (${fallback}): `, fallback);
+  const stem = slugify(answer.replace(/\.md$/i, '')) || fallback;
+  const dir = resolve(process.cwd(), stem);
+  if (existsSync(dir) && statSync(dir).isDirectory() && findDeckInDir(dir)) {
+    // A deck already lives here — open it instead of clobbering anything.
+    return findDeckInDir(dir);
+  }
+  return scaffoldDeck(resolve(dir, `${stem}.md`));
+}
+
 function scaffoldDeck(deckPath) {
   const templatePath = resolve(__dirname, 'templates', 'slides.md');
   try {
@@ -169,7 +187,7 @@ async function loadUserConfig(source) {
 }
 
 const { cmd, theme: cliTheme, file } = parseArgs(process.argv);
-const deckFile = await resolveDeck(file);
+const deckFile = file ? await resolveDeck(file) : await scaffoldNewProject();
 const source = dirname(deckFile);
 
 ensureDefaultConfig(source);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exor404/mdslides",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Markdown in, presentation out.",
   "type": "module",
   "bin": {