|
1 | 1 | # CodeAppsCompact |
2 | 2 |
|
3 | | -**Install the skill. Ask for a Code Apps record screen. The agent obtains the kit only when it is missing.** |
| 3 | +**Install one skill. Its record-screen kit is already included.** |
4 | 4 |
|
5 | | -CodeAppsCompact is a GitHub-hosted React/TypeScript kit and portable agent skill for Power Platform Code Apps. The agent configures fields, columns, validation, and generated-service mappings instead of regenerating list/editor behavior. |
| 5 | +CodeAppsCompact helps an agent build Power Platform Code Apps by configuring a reusable React/TypeScript screen instead of rewriting its list, form, paging, validation, and error handling. |
6 | 6 |
|
7 | | -**Status:** 0.1.1, experimental, MIT-licensed. The kit and skill are distributed through [GitHub Releases](https://github.com/ilyafainberg/CodeAppsCompact/releases/tag/v0.1.1), not the npm registry. Live Power Apps-host and tenant compatibility remain unverified. Version 0.1.1 changes distribution and documentation; the 0.1.0 component behavior is unchanged. |
| 7 | +**0.1.2 - experimental, MIT-licensed.** Distributed through GitHub, not the npm registry. Live Power Apps-host and tenant compatibility remain unverified. This release changes packaging, not component behavior. |
8 | 8 |
|
9 | | -## 1. Install the skill |
| 9 | +## Install the skill |
10 | 10 |
|
11 | | -This repository is a single-plugin skill marketplace named `codeappscompact`. It contains one plugin and one skill, both named `codeappscompact`. Register it explicitly in your agent; the repository is not automatically listed in every host's central catalog. |
| 11 | +This repository is a single-plugin marketplace. Register it in your agent: |
12 | 12 |
|
13 | | -### GitHub Copilot CLI |
14 | | - |
15 | | -Run in your terminal: |
| 13 | +**GitHub Copilot CLI** (terminal): |
16 | 14 |
|
17 | 15 | ```powershell |
18 | 16 | copilot plugin marketplace add ilyafainberg/CodeAppsCompact |
19 | 17 | copilot plugin install codeappscompact@codeappscompact |
20 | 18 | ``` |
21 | 19 |
|
22 | | -### Claude Code |
23 | | - |
24 | | -Run inside a Claude Code session: |
| 20 | +**Claude Code** (inside a session): |
25 | 21 |
|
26 | 22 | ```text |
27 | 23 | /plugin marketplace add ilyafainberg/CodeAppsCompact |
28 | 24 | /plugin install codeappscompact@codeappscompact |
29 | 25 | ``` |
30 | 26 |
|
31 | | -### Other Agent Skills-compatible hosts |
32 | | - |
33 | | -Download [codeappscompact-skill-0.1.1.zip](https://github.com/ilyafainberg/CodeAppsCompact/releases/download/v0.1.1/codeappscompact-skill-0.1.1.zip) and import its `codeappscompact` folder through your host's supported skill mechanism. Alternatively, copy the complete [skill directory](plugins/codeappscompact/skills/codeappscompact), including `references`, to a supported skill location. Copying only `SKILL.md` loses the installation instructions and pinned kit manifest. |
34 | | - |
35 | | -The skill is host-neutral guidance, not an executable installer or a grant of permissions. Installation does not run hooks, register MCP servers, download the runtime kit, change a Code App, or deploy anything. The agent performs those kit setup steps only when you invoke the skill for an authorized task. Reload your host if it requires a new session to discover installed skills. |
36 | | - |
37 | | -## 2. Ask for the feature |
38 | | - |
39 | | -In an existing React/TypeScript Code App, for example: |
40 | | - |
41 | | -> Use CodeAppsCompact to add a service-request screen using our existing generated service. Include summary, owner email, priority, and estimated hours. Support creating, editing, paging, and searching loaded records. Preserve the existing theme and do not deploy. |
42 | | -
|
43 | | -The skill guides the agent to: |
44 | | - |
45 | | -1. Inspect the app, package manager, generated service types, and requested behavior. |
46 | | -2. Reuse a compatible installed `codeappscompact` package. If it is declared but not restored, restore the existing lockfile instead of replacing its origin or version. |
47 | | -3. If absent, obtain any required permission, download the version-pinned kit from this repository's GitHub release, verify SHA-256, inspect its contents, and install it project-locally. No npm login is needed for the kit. |
48 | | -4. Read the installed version's `API.txt` and write only the app-specific configuration and service adapter. |
49 | | -5. Run the app's checks and report whether integration used synthetic data or authorized live services. A synthetic pass does not establish tenant compatibility. |
50 | | - |
51 | | -The default downloaded archive is kept inside the consuming app's `vendor` directory and installed as a local file dependency. Keep that archive, the dependency manifest, and the lockfile together in the app repository so a clean checkout can restore it. A valid existing installation is reused without another download or update check. Upgrades are explicit. |
52 | | - |
53 | | -**GitHub replaces kit hosting, not dependency management.** The package import remains `codeappscompact`; npm, pnpm, or Yarn can install the verified archive. React, TanStack React Query, and the Power Apps SDK remain peer dependencies and may still require your configured package registry. The skill does not bypass registry, TLS, tenant, or tool-permission restrictions. |
54 | | - |
55 | | -## What the kit handles |
| 27 | +**Other Agent Skills hosts:** import [codeappscompact-skill-0.1.2.zip](https://github.com/ilyafainberg/CodeAppsCompact/releases/download/v0.1.2/codeappscompact-skill-0.1.2.zip), or copy the complete [skill folder](plugins/codeappscompact/skills/codeappscompact) through your host's supported mechanism. Preserve `assets` and `references`; importing only the text of `SKILL.md` is insufficient. Existing users must update or reinstall the complete skill to receive the bundle. Reload the host if it requires a new session. |
56 | 28 |
|
57 | | -`RecordScreen` provides a record table, search over loaded records, cursor-based pagination and deduplication, accessible create/edit forms, primitive field validation, and visible read/write errors. Failed writes preserve the form; writes are not automatically retried. Refresh failure after a committed save does not replay the write. |
| 29 | +The skill contains everything specific to CodeAppsCompact: |
58 | 30 |
|
59 | | -The app supplies a `DataService<R, D>` with `getAll`, `create`, and `update` returning the Power Apps SDK's `IOperationResult<T>`, plus fields, columns, defaults, identity, and draft mappings. A caller-owned `QueryClientProvider` is required. The library injects no styles and creates no query client. |
60 | | - |
61 | | -Supported drafts are flat objects with widened `string` and `number` values. There is no delete, relationship editor, upload, nested draft schema, server-side search, or cross-system transaction support. Authentication, SDK setup, connections, permissions, and deployment remain the Code App's responsibility. Inspect real generated connector signatures rather than assuming they match the synthetic example. Unsupported requirements must stay visible, not be silently dropped. |
62 | | - |
63 | | -## Reference and manual use |
64 | | - |
65 | | -- [Portable skill](plugins/codeappscompact/skills/codeappscompact/SKILL.md): compact agent workflow. |
66 | | -- [Kit installation and reuse](plugins/codeappscompact/skills/codeappscompact/references/install.md): host-neutral procedure and an npm example. |
67 | | -- [Pinned kit manifest](plugins/codeappscompact/skills/codeappscompact/references/kit.json): release URL, supported installed versions, and SHA-256. |
68 | | -- [API.txt](API.txt): complete public API and behavior contract; also included in the kit. |
69 | | -- [examples/App.tsx](examples/App.tsx): configured screen. [examples/main.tsx](examples/main.tsx) supplies the query provider; [examples/service.ts](examples/service.ts) is explicitly synthetic. |
70 | | - |
71 | | -The kit archive contains compiled JavaScript, TypeScript declarations, API documentation, synthetic examples, README, and LICENSE. It has no install lifecycle hook. After following the verification procedure, an npm project can install its local archive: |
72 | | - |
73 | | -```powershell |
74 | | -npm install --save-exact --ignore-scripts --no-audit --no-fund ".\vendor\codeappscompact-0.1.1.tgz" |
| 31 | +```text |
| 32 | +codeappscompact/ |
| 33 | + SKILL.md |
| 34 | + LICENSE |
| 35 | + references/ |
| 36 | + install.md |
| 37 | + kit.json |
| 38 | + assets/ |
| 39 | + codeappscompact-0.1.2.tgz |
75 | 40 | ``` |
76 | 41 |
|
77 | | -Import normally: |
78 | | - |
79 | | -```typescript |
80 | | -import { RecordScreen, type DataService } from 'codeappscompact'; |
81 | | -``` |
| 42 | +The archive includes prebuilt JavaScript, TypeScript declarations, `API.txt`, a synthetic example, package metadata, and the MIT license. No separate kit download or source build is needed. |
82 | 43 |
|
83 | | -Do not use `npm install codeappscompact` without the archive path: this project does not publish the kit to the npm registry, and a registry name is not proof of this repository's provenance. |
| 44 | +## Use it |
84 | 45 |
|
85 | | -## Evidence and limits |
| 46 | +In an existing React/TypeScript Code App, ask: |
86 | 47 |
|
87 | | -The reusable implementation, rather than the skill's wording, is the token-saving mechanism. The earlier 0.1.0 pilot reported 78.6% fewer model-output tokens and 42.8% fewer total tokens across three paired authoring trials of one synthetic record-management feature. Input documentation was counted. This does not establish savings across all applications, against every existing framework, or for this newly packaged installation workflow. Skill discovery, downloads, and first-time dependency setup have their own costs; no new token benchmark is claimed here. |
| 48 | +> Use CodeAppsCompact to add a service-request screen using our existing generated service. Include summary, owner email, priority, and estimated hours. Support creating, editing, paging, and searching loaded records. Preserve the theme and do not deploy. |
88 | 49 |
|
89 | | -Private benchmark prompts, usage logs, and trial sources are not included. The synthetic example and tests are not a connected or deployed Power Apps app. |
| 50 | +The agent reuses a supported installed kit. If absent, it verifies the bundled archive, copies it into the app's `vendor` directory, and installs that local file with the app's package manager. It then reads the installed API and writes only your fields, columns, validation, and typed service adapter. Keep the vendored archive, dependency manifest, and lockfile together in the app repository. |
90 | 51 |
|
91 | | -## Develop and run the synthetic example |
| 52 | +The skill assumes its assets are present. An incomplete or corrupt installation is an error: reinstall the complete skill rather than fetching a substitute or regenerating the component. Existing locked dependencies and custom packages are not silently replaced. |
92 | 53 |
|
93 | | -Use Node.js 22.12 or newer; CI uses Node.js 24. The lockfile pins development dependencies, including React 18 and Power Apps SDK 1.5.0. |
| 54 | +**Bundled does not mean a complete offline app environment.** Node.js >=22.12.0, React, TanStack React Query, and the Power Apps SDK are still required. Missing dependencies may need your configured registry. No npm account is needed for this kit. Installation runs no skill hooks and grants no tool permissions; modifying an app still requires authorization. |
94 | 55 |
|
95 | | -```powershell |
96 | | -git clone https://github.com/ilyafainberg/CodeAppsCompact.git |
97 | | -cd CodeAppsCompact |
98 | | -npm ci --ignore-scripts --no-audit --no-fund |
99 | | -npm run typecheck |
100 | | -npm test |
101 | | -npm run build |
102 | | -npm run build:demo |
103 | | -npm run dev |
104 | | -``` |
| 56 | +## Scope |
105 | 57 |
|
106 | | -Open Vite's printed loopback URL. The example uses in-memory synthetic data, makes no tenant requests, stores no credentials, and resets on reload. Neither build command publishes or deploys anything. |
| 58 | +`RecordScreen` supports lists, search over loaded records, cursor paging, create/edit/cancel, flat string/number drafts, and visible read/write errors. Failed saves preserve inputs; writes are not automatically retried. The app owns its query provider, styling, generated services, authentication, connections, permissions, and deployment. |
107 | 59 |
|
108 | | -## Distribution maintenance |
| 60 | +Delete, relationships, uploads, nested drafts, backend-wide search, and cross-system transactions are not supplied. The skill does not scaffold or deploy an app. Synthetic examples are not live integrations. |
109 | 61 |
|
110 | | -The root `marketplace.json` and `.claude-plugin/marketplace.json` expose the same catalog. `plugins/codeappscompact/plugin.json` uses the Agent Plugins 1.0 format; its `.claude-plugin/plugin.json` companion supports legacy hosts. The skill uses the standard `SKILL.md` format with local references and no host-specific tool requirements, hooks, or automatic updates. |
| 62 | +## Repository layout |
111 | 63 |
|
112 | | -For a new release, update the package, lockfile, plugin manifests, skill version, installation filenames, and kit manifest together. Run the checks, build, then use `npm pack --ignore-scripts` to produce the kit. Review the archive's files and compute its SHA-256 before updating the pinned kit manifest. Archive the complete skill directory only after that hash is recorded. Publish both archives and `SHA256SUMS` on a new GitHub release tag pointing to the reviewed commit; never replace an existing version's artifacts. Verify anonymous downloads, checksums, marketplace discovery, and installation in a separate consumer before announcing availability. |
| 64 | +- [Skill](plugins/codeappscompact/skills/codeappscompact/SKILL.md): instructions, local installation reference, and bundled kit. |
| 65 | +- [kit](kit/README.md): maintainer-only source, API, example, tests, and build tools. Consumers do not need this directory. |
| 66 | +- `marketplace.json` and `.claude-plugin`: discovery metadata for supported hosts. |
113 | 67 |
|
114 | | -`"private": true` intentionally blocks npm publishing while allowing local packing and installation. CI checks types, behavior, distribution metadata, library/demo builds, and package contents; it does not publish to npm, deploy Code Apps, or change tenant data. |
| 68 | +See [kit maintenance](kit/README.md) for development, release steps, and the earlier token pilot's evidence and limits. No new token-saving measurement is claimed for this packaging change. |
115 | 69 |
|
116 | 70 | Licensed under the [MIT License](LICENSE), copyright 2026 Ilya Fainberg. |
0 commit comments