@opencrs/cli 0.0.0 → 0.1.0

package/man/opencrs.1

@@ -0,0 +1,312 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH OPENCRS 1  OpenCRS "OpenCRS Manual"
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH NAME
+opencrs \- Check digital\-signage creative against the screens it\*(Aqs made for
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH SYNOPSIS
+\fBopencrs\fR <COMMAND>
+.br
+\fBopencrs\fR [\-h|\-\-help] [\-V|\-\-version]
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH DESCRIPTION
+Check digital\-signage creative against the screens it\*(Aqs made for
+.PP
+opencrs reads a publisher\*(Aqs screens.json files, which say what each screen needs, and a creative.json, which lists the files of one piece of creative, and checks the files against the screens they target. It can also find a publisher\*(Aqs files on the web and check which of them to trust, check any OpenCRS document against its schema, and run the conformance suite against a validator.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.PP
+Each command takes its own options; see COMMANDS. Every flag may also be written with a single dash and its full name (for example \-spec for \-\-spec), as in earlier versions.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help (\-\-help shows more)
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Show the version
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH COMMANDS
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SS "opencrs check"
+Check a creative\*(Aqs files against the screens they target.
+.PP
+Reads a creative.json, finds each file it lists, and checks the file\*(Aqs type, size, duration and layout against every screen it targets in the screens.json files you give. Each file\*(Aqs pixel size, byte size and SHA\-256 come from the file itself; the manifest\*(Aqs declared values are used only for a file that is missing or when \-\-no\-files is set.
+.PP
+\fBopencrs check\fR [OPTIONS] \-\-spec <SCREENS> <CREATIVE>
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TP
+\fB\-s\fR, \fB\-\-spec\fR \fI<SCREENS>\fR
+A screens.json to check against. Give it more than once to check against several publishers.
+.TP
+\fB\-\-files\fR \fI<DIR>\fR
+Directory holding the creative files. Defaults to the manifest\*(Aqs directory.
+.TP
+\fB\-\-no\-files\fR
+Use the manifest\*(Aqs declared values, don\*(Aqt read the files
+.TP
+\fB\-\-json\fR
+Print the reports as a JSON array of spec reports, in the spec\*(Aqs report format.
+.TP
+\fB\-\-now\fR \fI<TIME>\fR
+Validation time, RFC 3339 (default: now)
+.TP
+\fB\-\-margin\fR \fI<RATIO>\fR [default: 1.25]
+Warn when text is below this multiple of its minimum size. Zero means the default, 1.25.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help (\-\-help shows more)
+.TP
+<\fICREATIVE\fR>
+The creative.json to check
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SS "opencrs schema"
+Check documents against the OpenCRS schemas.
+.PP
+Each file is checked against the JSON Schema for its kind (index, screens, creative, report or rule\-pack), detected from the document unless \-\-kind is given. For a screens.json it also reports references to formats or venues that don\*(Aqt exist and rules that inheritance has made impossible to meet. A JSON array is checked element by element, so the output of check \-\-json works.
+.PP
+\fBopencrs schema\fR [OPTIONS] <FILE>...
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TP
+\fB\-\-kind\fR \fI<KIND>\fR
+Document kind: index, screens, creative, report or rule\-pack. Detected from the document when omitted.
+.TP
+\fB\-\-allow\-local\-http\fR
+Accept http://localhost document URLs in an index
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help (\-\-help shows more)
+.TP
+<\fIFILE\fR>
+The documents to check
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SS "opencrs resolve"
+Show the requirements for a format or a screen.
+.PP
+Prints the requirements that apply to one format or one screen after inheritance (publisher, network, venue, format, screen) as JSON. A reference is <publisher>/<network>/<format> or <publisher>/<network>/screen/<id>.
+.PP
+\fBopencrs resolve\fR <SCREENS> <REF>
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help (\-\-help shows more)
+.TP
+<\fISCREENS\fR>
+The screens.json to read
+.TP
+<\fIREF\fR>
+A format or screen reference: <publisher>/<network>/<format> or <publisher>/<network>/screen/<id>.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SS "opencrs fetch"
+Find a publisher\*(Aqs specs and check which to trust.
+.PP
+Given a domain, reads the publisher\*(Aqs index at /.well\-known/opencrs.json, fetches each document it lists, follows delegations, and marks each document trusted, expired, rejected, skipped (a partner document without a token) or failed, with the reason. Given a document URL, checks that its publisher vouches for that exact URL.
+.PP
+Only HTTPS is used, and addresses on private networks are refused. See the NETWORK section of the man page for the limits.
+.PP
+\fBopencrs fetch\fR [OPTIONS] <DOMAIN|URL>
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TP
+\fB\-\-token\fR \fI<DOMAIN=TOKEN>\fR
+Bearer token a publisher issued for its partner documents, as DOMAIN=TOKEN. Give it more than once for several publishers. The token is sent only to that domain.
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fI<DIR>\fR
+Save trusted documents, exactly as served, under this directory. The files are ready for check \-\-spec. When partner documents are included, a merged.screens.json is written too.
+.TP
+\fB\-\-json\fR
+Print the result as JSON
+.TP
+\fB\-\-allow\-local\-http\fR
+Local testing: allow http:// and connections to localhost, 127.0.0.1 and [::1]. Other internal addresses stay refused.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help (\-\-help shows more)
+.TP
+<\fIDOMAIN|URL\fR>
+A publisher\*(Aqs domain, or the URL of one document
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SS "opencrs conformance"
+Run the conformance suite against a validator.
+.PP
+Runs the cases in the conformance directory against this tool\*(Aqs own validator, or against another validator given with \-\-cmd. The command is run through the shell with each case directory as its last argument and must print the reports as a JSON array.
+.PP
+\fBopencrs conformance\fR [OPTIONS] [DIR]
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TP
+\fB\-\-level\fR \fI<LEVEL>\fR [default: full]
+Level to test: core, layout or full
+.TP
+\fB\-\-cmd\fR \fI<COMMAND>\fR
+External validator to test. It is run with each case directory as its last argument and must print the reports as a JSON array.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+List passing cases too
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help (\-\-help shows more)
+.TP
+[\fIDIR\fR] [default: conformance/0.1]
+The conformance directory
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SS "opencrs completion"
+Print shell completions.
+.PP
+Prints a completion script for the shell to standard output. Save it where your shell looks for completions, or load it from your shell\*(Aqs startup file.
+.PP
+\fBopencrs completion\fR <SHELL>
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help (\-\-help shows more)
+.TP
+<\fISHELL\fR>
+The shell to print completions for
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+bash
+.IP \(bu 2
+zsh
+.IP \(bu 2
+fish
+.IP \(bu 2
+powershell
+.RE
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SS "opencrs version"
+Show the tool, spec and rule pack versions.
+.PP
+\fBopencrs version\fR
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show help (\-\-help shows more)
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH EXAMPLES
+.PP
+Check a creative against a publisher\*(Aqs screens:
+.PP
+.RS 4
+.nf
+opencrs check \-\-spec retail.screens.json creative.json
+.fi
+.RE
+.PP
+Check against two publishers and save the reports as JSON:
+.PP
+.RS 4
+.nf
+opencrs check \-s retail.screens.json \-s airports.screens.json \\
+    \-\-json creative.json > reports.json
+.fi
+.RE
+.PP
+Check a screens.json and a creative.json against the schemas:
+.PP
+.RS 4
+.nf
+opencrs schema screens.json creative.json
+.fi
+.RE
+.PP
+Show what a screen requires:
+.PP
+.RS 4
+.nf
+opencrs resolve retail.screens.json harbourline.example/retail/screen/HC\-L1\-002
+.fi
+.RE
+.PP
+Find a publisher\*(Aqs specs and save the ones to trust:
+.PP
+.RS 4
+.nf
+opencrs fetch \-\-output specs harbourline.example
+.fi
+.RE
+.PP
+Install the zsh completions:
+.PP
+.RS 4
+.nf
+opencrs completion zsh > ~/.zfunc/_opencrs
+.fi
+.RE
+.SH "EXIT STATUS"
+.PP
+All commands exit 0 on success, 1 when what they checked failed, and 2 for a usage error or a file that could not be read. Asking for help or the version exits 0.
+.TP
+\fBcheck\fR
+0 passed, 1 a file failed, 2 usage or read error
+.TP
+\fBschema\fR
+0 all valid, 1 a document failed, 2 usage or read error
+.TP
+\fBresolve\fR
+0 resolved, 1 reference not found, 2 usage or read error
+.TP
+\fBfetch\fR
+0 all trusted, 1 a document was not trusted, 2 usage or fetch error
+.TP
+\fBconformance\fR
+0 conforms, 1 a case failed, 2 usage or read error
+.SH ENVIRONMENT
+.TP
+\fBNO_COLOR\fR
+When set to a non\-empty value, help and error messages are never coloured. They are also plain when output is not a terminal, or when TERM is dumb.
+.TP
+\fBCLICOLOR_FORCE\fR
+When set to a value other than 0, colour is used even when output is not a terminal (NO_COLOR still wins).
+.TP
+\fBHTTP_PROXY, HTTPS_PROXY\fR
+Ignored by fetch. A proxy would resolve host names where the addresses can\*(Aqt be checked, so fetch always connects directly.
+.SH NETWORK
+.PP
+Only fetch uses the network. It is built so that an index cannot point it at a service on the machine or its network.
+.TP
+\fBScheme\fR
+Only https:// URLs are fetched. With \-\-allow\-local\-http, http:// is allowed for localhost, 127.0.0.1 and [::1] only.
+.TP
+\fBAddresses\fR
+Each host, redirects included, is resolved once and refused if any of its addresses is loopback, private, link\-local, shared (CGNAT), multicast, broadcast, unspecified, reserved or for documentation. The connection goes to the addresses that were checked. With \-\-allow\-local\-http, loopback is allowed for localhost, 127.0.0.1 and [::1] only; other internal addresses stay refused.
+.TP
+\fBRedirects\fR
+At most four, and only to https://. A redirect to another host is refused for a document that must stay on its publisher\*(Aqs host and for any request that carries a token.
+.TP
+\fBTime\fR
+Each request, redirects included, must finish within 30 seconds.
+.TP
+\fBSize\fR
+A document larger than 50 MiB (52428800 bytes) is refused. One discovery reads at most 512 MiB in total, indexes and documents together.
+.TP
+\fBIndex entries\fR
+An index may list at most 1000 documents, and at most 1000 delegates.
+.TP
+\fBTokens\fR
+A \-\-token is sent only with requests for that publisher\*(Aqs partner documents.
+.SH "SEE ALSO"
+The OpenCRS specification: https://opencrs.dev/spec/0.1/

package/npm-shrinkwrap.json

@@ -0,0 +1,52 @@
+{
+  "lockfileVersion": 3,
+  "name": "@opencrs/cli",
+  "packages": {
+    "": {
+      "bin": {
+        "opencrs": "run-opencrs.js"
+      },
+      "dependencies": {
+        "detect-libc": "^2.1.2"
+      },
+      "devDependencies": {
+        "prettier": "^3.9.6"
+      },
+      "engines": {
+        "node": ">=14.14",
+        "npm": ">=6"
+      },
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "name": "@opencrs/cli",
+      "version": "0.1.0"
+    },
+    "node_modules/detect-libc": {
+      "engines": {
+        "node": ">=8"
+      },
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "version": "2.1.2"
+    },
+    "node_modules/prettier": {
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "dev": true,
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      },
+      "integrity": "sha512-OpN0zzVdiaiAhxpuuj5efpIS4sY9j7bY6uR5mnj5yPzGkdkjNKSJeUThPb60Jw29QuAZgA4o+/iB49kFiaBX6g==",
+      "license": "MIT",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.9.6.tgz",
+      "version": "3.9.6"
+    }
+  },
+  "requires": true,
+  "version": "0.1.0"
+}

package/package.json

@@ -1,7 +1,130 @@
 {
-  "name": "@opencrs/cli",
-  "version": "0.0.0",
-  "description": "The OpenCRS command-line validator. Placeholder; the first real release follows.",
+  "artifactDownloadUrls": [
+    "https://github.com/OpenCRS-Org/opencrs/releases/download/v0.1.0"
+  ],
+  "bin": {
+    "opencrs": "run-opencrs.js"
+  },
+  "dependencies": {
+    "detect-libc": "^2.1.2"
+  },
+  "description": "Tooling for OpenCRS, the Open Creative Requirements Specification",
+  "devDependencies": {
+    "prettier": "^3.9.6"
+  },
+  "engines": {
+    "node": ">=14.14",
+    "npm": ">=6"
+  },
+  "glibcMinimum": {
+    "major": 2,
+    "series": 35
+  },
+  "homepage": "https://opencrs.dev",
+  "keywords": [
+    "opencrs",
+    "dooh",
+    "creative",
+    "specification"
+  ],
   "license": "Apache-2.0",
-  "homepage": "https://opencrs.dev"
-}
+  "name": "@opencrs/cli",
+  "preferUnplugged": true,
+  "repository": "https://github.com/OpenCRS-Org/opencrs",
+  "scripts": {
+    "fmt": "prettier --write **/*.js",
+    "fmt:check": "prettier --check **/*.js",
+    "postinstall": "node ./install.js"
+  },
+  "supportedPlatforms": {
+    "aarch64-apple-darwin": {
+      "artifactName": "opencrs-cli-aarch64-apple-darwin.tar.xz",
+      "bins": {
+        "opencrs": "opencrs"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-pc-windows-gnu": {
+      "artifactName": "opencrs-cli-aarch64-pc-windows-msvc.zip",
+      "bins": {
+        "opencrs": "opencrs.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "aarch64-pc-windows-msvc": {
+      "artifactName": "opencrs-cli-aarch64-pc-windows-msvc.zip",
+      "bins": {
+        "opencrs": "opencrs.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "aarch64-unknown-linux-gnu": {
+      "artifactName": "opencrs-cli-aarch64-unknown-linux-gnu.tar.xz",
+      "bins": {
+        "opencrs": "opencrs"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-musl-dynamic": {
+      "artifactName": "opencrs-cli-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "opencrs": "opencrs"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-musl-static": {
+      "artifactName": "opencrs-cli-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "opencrs": "opencrs"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-apple-darwin": {
+      "artifactName": "opencrs-cli-x86_64-apple-darwin.tar.xz",
+      "bins": {
+        "opencrs": "opencrs"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-pc-windows-gnu": {
+      "artifactName": "opencrs-cli-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "opencrs": "opencrs.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "x86_64-pc-windows-msvc": {
+      "artifactName": "opencrs-cli-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "opencrs": "opencrs.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "x86_64-unknown-linux-gnu": {
+      "artifactName": "opencrs-cli-x86_64-unknown-linux-gnu.tar.xz",
+      "bins": {
+        "opencrs": "opencrs"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-musl-dynamic": {
+      "artifactName": "opencrs-cli-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "opencrs": "opencrs"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-musl-static": {
+      "artifactName": "opencrs-cli-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "opencrs": "opencrs"
+      },
+      "zipExt": ".tar.xz"
+    }
+  },
+  "version": "0.1.0",
+  "volta": {
+    "node": "18.14.1",
+    "npm": "9.5.0"
+  }
+}

package/run-opencrs.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { run } = require("./binary");
+run("opencrs");