portaljs-add-resource

# PortalJS — Add Resource

## Overview

Add a resource — an additional file — to a dataset that already exists in a
`portaljs-catalog` portal. Where `/portaljs-add-dataset` creates a **new** dataset
(one file), this skill adds a file to an **existing** one: a data dictionary, a
methodology document, or another data file (e.g. a second year's figures).

Mirrors the Frictionless Data Package model: a dataset holds a `resources[]` array,
and the showcase at `/@<namespace>/<slug>` renders one section per resource (preview,
schema, download). A single-file dataset migrates to `resources[]` automatically the
first time a second file is added — no data is lost.

## Prerequisites

- An existing PortalJS portal (`portaljs-catalog` template) with `datasets.json`,
  `package.json`, and `pages/[owner]/[slug].tsx` present.
- The target dataset already registered in `datasets.json`.
- The new resource's source: a local file path or a public URL, in CSV, TSV, JSON
  (array), or GeoJSON format.
- Node 18+ installed to run `npx next build` for verification.

## Instructions

The canonical, full step-by-step workflow lives in
[`.claude/commands/portaljs-add-resource.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-resource.md)
in this repository — that file is the single source of truth. Read and follow it. Summary:

1. Gather input (interview if thin): `DATASET` (slug or `namespace/slug`), `SOURCE`
   (path or URL), `PORTAL_DIR` (default `.`), `RESOURCE_NAME`, `RESOURCE_TITLE`,
   `DESCRIPTION`. If `DATASET` or `SOURCE` is missing, list datasets from
   `datasets.json` and ask.
2. Validate the portal and locate the dataset entry by slug (and namespace, if
   given). If the dataset does not exist, offer `/portaljs-add-dataset` instead.
3. Detect the format from extension/Content-Type, fetch (check HTTP status) or
   confirm the local path exists, then copy into `PORTAL_DIR/public/data/` under a
   non-colliding filename.
4. Update `datasets.json`: if the dataset has no `resources` yet, migrate its
   top-level `file`/`format`/`schema` into the first resource (lossless), then
   append the new resource; if `resources` already exists, just append, keeping
   `name` unique within the array.
5. Verify the build with `npx next build`, capturing output to a log file; fix
   malformed JSON before reporting success.
6. Report the outcome (see Output below).

## Output

```
✓ Resource added to DATASET: RESOURCE_TITLE (RESOURCE_NAME.EXT)
  - Data file: public/data/RESOURCE_NAME.EXT
  - Manifest:  datasets.json (dataset now has <n> resources)
  - Showcase:  /@<namespace>/<slug> renders a section per resource
```

If this was the first migration to multi-resource, note that the dataset's single
`file` was moved into `resources[]` with no data lost.

## Error Handling

| Symptom | Cause | Fix |
|---|---|---|
| "Dataset not found" | `DATASET` slug/namespace doesn't match any entry in `datasets.json` | List datasets from `datasets.json` and ask the user to pick, or run `/portaljs-add-dataset` to create it |
| `npx next build` fails with a JSON parse error | Manually edited `datasets.json` has a trailing comma or unescaped character | Re-open the file, fix the JSON, and rebuild before reporting success |
| Resource file fails to fetch (non-2xx) | `SOURCE` URL is wrong, private, or the host is down | Confirm the URL in a browser or with `curl -I SOURCE`; ask for a corrected URL or a local path |
| New resource's filename collides with an existing one in `/public/data` | Auto-derived `RESOURCE_NAME` matches an existing file stem | Pick a distinct `RESOURCE_NAME`, or let the skill append a numeric suffix |
| Showcase doesn't render the new section after build | `name` in the new resource object duplicates an existing resource's `name` | Rename the resource's `name` to something unique within that dataset's `resources[]` |

## Examples

### Example 1 — Add a data dictionary to a single-file dataset

```
/portaljs-add-resource orders ./data/orders-data-dictionary.csv --title "Data dictionary"
```
`orders` was a single CSV. It is migrated to a two-resource dataset (the original
data plus the dictionary), and its showcase now renders a section for each.

### Example 2 — Add a resource by URL to a dataset that already has resources

```
/portaljs-add-resource climate-observations https://example.org/data/methodology.json --name methodology --title "Methodology notes"
```
The skill fetches the URL, checks the HTTP status, copies it to
`public/data/methodology.json`, and appends it to the existing `resources[]` array.

### Example 3 — Run with no arguments (interview mode)

```
/portaljs-add-resource
```
With no arguments, the skill lists datasets from `datasets.json`, asks which one to
extend and for the new file's path or URL, then proceeds through steps 2-6 above.

## Resources

- [`.claude/commands/portaljs-add-resource.md`](https://github.com/datopian/portaljs/blob/main/.claude/commands/portaljs-add-resource.md) — canonical workflow this skill follows
- [`references/reference.md`](references/reference.md) — resource entry fields, single-to-multi-resource layout, troubleshooting
- Related skills: `/portaljs-add-dataset` (create a new dataset), `/portaljs-define-schema` (describe a resource's fields)
- [Frictionless Data — Data Package resources](https://datapackage.org/standard/data-resource/) — the data model this feature mirrors