Retire the legacy CLI and document native operator workflows
This commit is contained in:
@@ -11,6 +11,7 @@ and the HTTP service according to the boundary your application needs.
|
||||
- CLI subprocess: [subprocess integration](../integrations/subprocess.md)
|
||||
- HTTP service: [HTTP API reference](../api.md)
|
||||
- Application configuration: [configuration reference](../config.md)
|
||||
- Existing CLI callers: [native CLI migration](upgrading-cli.md)
|
||||
|
||||
Go applications that need an in-process prompt framework should import
|
||||
`go.maximumdirect.net/promptkit` directly. The tagged
|
||||
@@ -27,7 +28,7 @@ Consumers are responsible for:
|
||||
- supplying required inputs and template variables;
|
||||
- supplying credentials through the chosen interface;
|
||||
- protecting rendered prompts and generated artifacts as potentially
|
||||
sensitive;
|
||||
sensitive, including native inspection and full result reports;
|
||||
- deciding whether validation-failed output is usable; and
|
||||
- retrying only when another model call is acceptable.
|
||||
|
||||
|
||||
95
docs/consumers/upgrading-cli.md
Normal file
95
docs/consumers/upgrading-cli.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Migrate To The Native CLI
|
||||
|
||||
This guide covers Scriptorium's breaking CommandKit-native CLI cutover. It does
|
||||
not select a release version or change historical release notes. The
|
||||
[CLI reference](../cli.md) owns current syntax, streams, and statuses;
|
||||
[configuration](../config.md) owns source discovery and settings.
|
||||
The earlier [PromptKit upgrade](upgrading-promptkit.md) covers framework formats,
|
||||
not a compatibility layer for this interface.
|
||||
|
||||
## Replace Commands And Selections
|
||||
|
||||
| Former interface | Current interface |
|
||||
| --- | --- |
|
||||
| `run --prompt ID` / `--prompt-id` | `run ID`; exactly one positional prompt ID. |
|
||||
| `render --prompt ID` | `promptkit show prepared ID`. |
|
||||
| `inspect prompt --prompt ID` | `promptkit show prompt ID`. |
|
||||
| `inspect profile --profile ID` | `promptkit show profile ID`. |
|
||||
| `inspect configuration ...` | Native `config ... --scope promptkit`. |
|
||||
| Application `config ...` | Native `config ... --scope app` (the default scope), including diff. |
|
||||
| `--config-overlay` | `--overlay NAME`; a native overlay name, not an arbitrary path. |
|
||||
| `--input NAME=PATH` | `--input-file NAME=PATH`; `--input` now means literal text. |
|
||||
| `--llm-base-url` | `--endpoint` (canonical `--llm-endpoint`). |
|
||||
| Duration-valued `--timeout` | Integer `--timeout-seconds` for each generation attempt. |
|
||||
| `--out` / output-file flags | Caller stdout redirection. |
|
||||
| `--execution-report` | `--report PATH` with native result rendering. |
|
||||
|
||||
Prefer native short aliases such as `--profile`, `--var`, `--input-text`, and
|
||||
`--input-file`; canonical `--llm-*` spellings remain available.
|
||||
There is no duplicate prompt flag, direct backend-ID override, or retained
|
||||
`--profile-id` alias on generation.
|
||||
|
||||
Repeat mappings rather than comma-separating them. The first equals sign splits
|
||||
each mapping; commas and later equals signs are literal. Input text/file
|
||||
occurrences share native last-occurrence precedence.
|
||||
|
||||
## Migrate Application Configuration
|
||||
|
||||
Replace the source-selector list and top-level schema directory with
|
||||
`promptkit.configuration` and `promptkit.schema_dir`.
|
||||
The [maintained example](../../examples/config.yml) selects a separate framework
|
||||
entry file that imports prompt/profile/backend definitions through native
|
||||
ConfigKit composition. No source/schema CLI flags or compatibility conversion
|
||||
remain. Do not embed framework definitions inside the application section.
|
||||
|
||||
Discovery now uses native cwd, user-config, home, then Unix-system presets and
|
||||
their filename conventions. It is no longer limited to the two former
|
||||
`config.yml` paths. Set an explicit config path when migrating unattended jobs.
|
||||
Overlays remain native name selections. Application-scope native `--set` records
|
||||
retain conflict rejection; order does not make duplicate paths authoritative.
|
||||
There are no custom source/schema/HTTP selectors under `config`.
|
||||
|
||||
## Capture Artifacts And Reports
|
||||
|
||||
For an artifact file plus full native report, from the repository root:
|
||||
|
||||
```sh
|
||||
scriptorium run generic.markdown_summary --config examples/config.yml \
|
||||
--input-file transcript=examples/fixtures/transcript.md \
|
||||
--input-file glossary=examples/fixtures/glossary.yml \
|
||||
--report run-result.json --report-format json > summary.md
|
||||
```
|
||||
|
||||
This generation example contacts the configured provider. Use native prepared
|
||||
preview instead when only checking inputs/settings.
|
||||
|
||||
Main automatic/text output is the artifact alone, with no added newline.
|
||||
Main JSON/YAML is the native result; artifact bytes use native structured
|
||||
serialization. Separate reports contain that full native result, not the old
|
||||
observer-derived metadata shape. `--report-format` independently chooses
|
||||
text/YAML/JSON; omission leaves the format unset for native automatic rendering
|
||||
(currently YAML for structured values). Extensions do not select formats.
|
||||
|
||||
Omit quiet to capture main output, including redirected stdout. Quiet still
|
||||
allows an explicitly requested report file. Reports are available only when a
|
||||
result is returned; resultless failures do not replace an existing report.
|
||||
Partial delivery can leave one or both destinations written. Keep paths separate
|
||||
and check status/diagnostics before treating files as fresh.
|
||||
|
||||
## Adjust Status And Sensitivity Handling
|
||||
|
||||
Completed generated-content validation failure is now domain status 4, not the
|
||||
old status 2. Native usage/invalid-configuration input is 2, diff-check
|
||||
differences are 3, and operational failures are 1. Presentation/file failures
|
||||
can change success into failure while preserving an already nonzero domain
|
||||
classification. The [CLI status table](../cli.md#server-and-statuses) owns details.
|
||||
|
||||
Native prompt inspection includes messages; prepared reports include rendered
|
||||
content; full run reports include generated content and metadata. Framework
|
||||
classified-field redaction does not make arbitrary report data safe to expose.
|
||||
|
||||
Requirements discovery is separate from validation/preparation: it can run
|
||||
before artifacts exist, and a partial report may succeed. Read its native
|
||||
completeness/issue fields. Smoke tests are explicit provider operations, not
|
||||
startup checks. See [subprocess guidance](../integrations/subprocess.md) for
|
||||
stream capture, cancellation, and caller responsibilities.
|
||||
@@ -1,33 +1,23 @@
|
||||
# Upgrade PromptKit Sources And Definitions
|
||||
|
||||
This guide covers the CLI and framework configuration cutover to
|
||||
This guide covers the earlier framework configuration cutover to
|
||||
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/configuration-migration.md)
|
||||
and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||
for the full upstream contract.
|
||||
for the full upstream contract. The subsequent [native CLI migration](upgrading-cli.md)
|
||||
owns command, reporting, application-discovery, and source-setting changes.
|
||||
|
||||
Removing version selectors and changing framework definition shapes are
|
||||
intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility).
|
||||
|
||||
## Application configuration
|
||||
|
||||
Existing application fields that already select the desired sources retain
|
||||
their meaning. For example, this application configuration works both before
|
||||
and after the cutover:
|
||||
|
||||
```yaml
|
||||
promptkit_sources:
|
||||
- directory: ./examples/prompts
|
||||
- directory: ./examples/profiles
|
||||
- file: ./examples/framework/backends.yml
|
||||
schema_dir: ./examples/schemas
|
||||
```
|
||||
|
||||
The selected framework files must still be rewritten as described below.
|
||||
Scriptorium uses one native application schema: discovery, imports, selected
|
||||
overlays, source order, explicit overrides, and working-directory-relative
|
||||
selector paths remain application configuration behavior. It loads framework
|
||||
sources separately with PromptKit's schema. No second application schema or
|
||||
legacy definition reader is provided. See the [configuration reference](../config.md).
|
||||
Framework definition migration and application acquisition are separate changes.
|
||||
Rewrite older framework files as below, then select their entry file using the
|
||||
current [application configuration](../config.md#application-settings).
|
||||
The old source-selector list and top-level schema root are not current aliases;
|
||||
follow the [CLI migration guide](upgrading-cli.md#migrate-application-configuration).
|
||||
Scriptorium does not provide a legacy definition reader or embedded-definition
|
||||
extraction/reload path.
|
||||
|
||||
## Rewrite framework definitions
|
||||
|
||||
@@ -82,9 +72,9 @@ Convert framework source controls from `configkit:` to `config:` and add
|
||||
header, if present, is `version: 2`. Use sibling inheritance such as
|
||||
`extends: {id: base}`.
|
||||
|
||||
Across ordered `promptkit_sources` entries, a later framework underlay replaces
|
||||
the whole record for the same ID. Supply the complete intended replacement,
|
||||
or create a distinct inherited record. Checkouts imported by the same
|
||||
The single external framework entry uses native ConfigKit import composition;
|
||||
there is no application-managed source-list precedence. Native record replacement
|
||||
and inheritance remain upstream-owned. Checkouts imported by the same
|
||||
[discovery file](../config.md#collection-checkout-discovery) are peers:
|
||||
conflicting definitions of the same ID fail instead of overriding one another.
|
||||
|
||||
@@ -106,5 +96,5 @@ records can replace it through ordinary composition.
|
||||
For multiple independently maintained repositories, see the
|
||||
[collection-discovery example](../../examples/config.discovery.yml). Its
|
||||
entry files declare their own namespaces; checkout names do not become IDs.
|
||||
The [CLI reference](../cli.md) demonstrates qualified rendering and the
|
||||
The [CLI reference](../cli.md) defines qualified selection and prepared preview; the
|
||||
[operations guide](../operations.md) describes when updates take effect.
|
||||
|
||||
Reference in New Issue
Block a user