Migrated to TypeScript.

docs/PACKAGING.md

@@ -1,94 +1,54 @@
-# Developing `hello-world` (ESM) Summary
+# Packaging sk-az-tools
 
-## Minimal Layout
-- `package.json`, `README.md`, `src/index.js` (ESM only).
-- `package.json` uses `"type": "module"` and explicit `exports`.
-- `files` allow-list to control shipped content.
+## Build model
 
-Example `package.json`:
-```json
-{
-  "name": "hello-world",
-  "version": "1.0.0",
-  "type": "module",
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "files": ["src", "README.md", "package.json"],
-  "engines": {
-    "node": ">=18"
-  }
-}
-```
+- Source lives in `src/` as TypeScript (`.ts`).
+- Runtime package is compiled to `dist/` using `npm run build`.
+- Public package entrypoints (`exports` and `bin`) point to `dist/**`.
 
-Example `src/index.js`:
-```js
-export function helloWorld() {
-  console.log("Hello World!!!");
-}
-```
+## Package surface
 
-## Sub-modules (Subpath Exports)
-- Expose sub-modules using explicit subpaths in `exports`.
-- Keep public API small and intentional.
+- `exports` defines what consumers can import.
+- `files` controls what is shipped to npm.
+- Current shipping content is `dist`, `README.md`, and `LICENSE`.
 
-Example:
-```json
-{
-  "exports": {
-    ".": "./src/index.js",
-    "./greetings": "./src/greetings.js",
-    "./callouts": "./src/callouts.js"
-  }
-}
-```
+## Development workflow
 
-## `exports` vs `files`
-- `exports` defines the public import surface (what consumers can import).
-- `files` defines what gets packaged; supports globs and negation.
+Build once:
 
-Example:
-```json
-{
-  "files": ["dist/**", "README.md", "!dist/**/*.map"]
-}
-```
-
-## Dev Workflow (Separate Repo, Live Updates)
-- Use `npm link` for live-edit development across repos.
-
-Publisher repo:
 ```bash
-npm link
+npm run build
 ```
 
-Consumer repo:
+Build in watch mode:
+
 ```bash
-npm link hello-world
+npm run build:watch
 ```
 
-Notes:
-- If you build to `dist/`, run a watch build so the consumer sees updates.
-- Unlink when done:
+Smoke check CLI output:
+
 ```bash
-npm unlink hello-world
+node dist/cli.js --help
 ```
 
-## Distribution as a `.tgz` Artifact
-- Create a tarball with `npm pack` and distribute the `.tgz` file.
-- Install directly from the tarball path.
-- Use `npm pack --dry-run` to verify contents before sharing.
-- The `.tgz` is written to the current working directory where `npm pack` is run.
-- You can redirect output with `--pack-destination` (or `pack-destination` config).
-- Ship `package.json` in the artifact, but exclude `package-lock.json` (keep it in the repo for development only).
+## Publish checklist
 
-Commands:
-```bash
-npm pack
-npm install ./hello-world-1.0.0.tgz
-```
+1. Run `npm run build` and ensure TypeScript compiles without errors.
+2. Verify package content with `npm pack --dry-run`.
+3. Create artifact: `npm pack --pack-destination ./artifacts`.
+4. Optionally install the artifact locally and validate CLI/imports.
+
+## Tarball usage
+
+Create package tarball:
 
-Example with output directory:
 ```bash
 npm pack --pack-destination ./artifacts
 ```
+
+Install from tarball:
+
+```bash
+npm install ./artifacts/@slawek/sk-az-tools-<version>.tgz
+```