winstore-startup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raghvendra Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# winstore-startup
+
+A Node.js native addon for managing Windows Store/UWP application startup tasks. This library provides programmatic control over whether your application automatically launches when Windows starts.
+
+## Features
+
+- Enable/disable startup tasks for Windows Store apps
+- Query current startup task state
+- Non-blocking async API (Promise-based)
+- Optional task ID (automatically uses first task if not specified)
+- TypeScript support with full type definitions
+- Graceful error handling with descriptive messages
+
+## Requirements
+
+- **OS:** Windows only
+- **Node.js:** >= 20.0.0
+- **Architecture:** x64 or arm64
+
+## Installation
+
+```bash
+npm install winstore-startup
+```
+
+The native addon is automatically compiled during installation.
+
+## Setup
+
+Before using this library, you must declare a startup task in your `AppxManifest.xml`. The library only manages existing startup tasks - it doesn't create them.
+
+### AppxManifest.xml Configuration
+
+Add the `desktop` namespace to your Package element:
+
+```xml
+<Package
+  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
+  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
+  ...>
+```
+
+Then add the startup task extension inside your Application element:
+
+```xml
+<Applications>
+  <Application Id="MyApp" Executable="app\MyApp.exe" EntryPoint="Windows.FullTrustApplication">
+    ...
+    <Extensions>
+      <desktop:Extension
+        Category="windows.startupTask"
+        Executable="app\MyApp.exe"
+        EntryPoint="Windows.FullTrustApplication">
+        <desktop:StartupTask TaskId="MyStartupTask" Enabled="false" DisplayName="My App" />
+      </desktop:Extension>
+    </Extensions>
+  </Application>
+</Applications>
+```
+
+**Note:** The `TaskId` is what you pass to `enable('MyStartupTask')`. If you only have one task, you can call `enable()` without arguments and it will auto-select it.
+
+## Usage
+
+### Basic Example
+
+```javascript
+const { enable, disable, getState } = require('winstore-startup');
+
+async function manageStartup() {
+  try {
+    // Enable auto-launch (uses first startup task automatically)
+    await enable();
+
+    // Check current state
+    const state = await getState();
+    console.log(state); // 2 = Enabled
+
+    // Disable auto-launch
+    await disable();
+  } catch (error) {
+    console.error('Failed to manage startup:', error.message);
+  }
+}
+
+manageStartup();
+```
+
+### With Specific Task ID
+
+```javascript
+const { enable, disable, getState } = require('winstore-startup');
+
+async function manageSpecificTask() {
+  // Enable a specific task
+  await enable('MyTaskId');
+
+  // Get state of a specific task
+  const state = await getState('MyTaskId');
+
+  // Disable a specific task
+  await disable('MyTaskId');
+}
+```
+
+### List All Startup Tasks
+
+```javascript
+const { getForCurrentPackage, StartupTaskState } = require('winstore-startup');
+
+async function listTasks() {
+  const tasks = await getForCurrentPackage();
+
+  for (const task of tasks) {
+    console.log(`Task: ${task.taskId}, State: ${task.state}`);
+  }
+}
+```
+
+### TypeScript
+
+```typescript
+import {
+  enable,
+  disable,
+  getState,
+  getForCurrentPackage,
+  StartupTaskState,
+} from 'winstore-startup';
+
+async function manageStartup(): Promise<void> {
+  try {
+    // Enable startup (uses first task if no ID provided)
+    const result = await enable();
+    if (result === StartupTaskState.Enabled) {
+      console.log('Startup enabled');
+    }
+
+    // With specific task ID
+    await enable('myTaskId');
+
+    // Get all tasks
+    const tasks = await getForCurrentPackage();
+    console.log(tasks);
+  } catch (error) {
+    console.error('Operation failed:', error);
+  }
+}
+```
+
+## API Reference
+
+### Functions
+
+| Function                 | Description                       | Returns                      |
+| ------------------------ | --------------------------------- | ---------------------------- |
+| `enable(taskId?)`        | Enable a startup task             | `Promise<StartupTaskState>`  |
+| `disable(taskId?)`       | Disable a startup task            | `Promise<void>`              |
+| `getState(taskId?)`      | Get the current state of a task   | `Promise<StartupTaskState>`  |
+| `getForCurrentPackage()` | Get all startup tasks for the app | `Promise<StartupTaskInfo[]>` |
+
+All functions return Promises and accept an optional `taskId` parameter (except `getForCurrentPackage`). If `taskId` is not provided, the first startup task from the current package is used automatically.
+
+### StartupTaskState Enum
+
+| Value | Name               | Description                       |
+| ----- | ------------------ | --------------------------------- |
+| 0     | `Disabled`         | Task is disabled                  |
+| 1     | `DisabledByUser`   | Task was disabled by the user     |
+| 2     | `Enabled`          | Task is enabled                   |
+| 3     | `DisabledByPolicy` | Task is disabled by system policy |
+| 4     | `EnabledByPolicy`  | Task is enabled by system policy  |
+
+### StartupTaskInfo Interface
+
+```typescript
+interface StartupTaskInfo {
+  taskId: string;
+  state: StartupTaskState;
+}
+```
+
+### Error Handling
+
+All functions throw errors with descriptive messages when:
+
+- No startup task is found in the app manifest
+- The specified task ID doesn't exist
+- The operation fails at the Windows API level
+- Running on a non-Windows platform
+
+```javascript
+try {
+  await enable();
+} catch (error) {
+  // Handle error - e.g., "No startup task found. Ensure your app manifest includes a startup task declaration."
+  console.error(error.message);
+}
+```
+
+## How It Works
+
+This library uses the Windows Runtime (WinRT) `StartupTask` API to manage application startup behavior. It compiles a native C++ addon using Node-API that bridges JavaScript to the Windows APIs.
+
+All operations are non-blocking - they run on a separate thread and return Promises, ensuring your Node.js event loop stays responsive.
+
+On non-Windows platforms, the functions reject with an error message indicating the platform is not supported.
+
+## Scripts
+
+```bash
+npm run build    # Rebuild the native addon
+npm run clean    # Clean build artifacts
+```
+
+## License
+
+MIT

package/binding.gyp

@@ -0,0 +1,28 @@
+{
+  "targets": [
+    {
+      "target_name": "winstore_startup",
+      "cflags!": ["-fno-exceptions"],
+      "cflags_cc!": ["-fno-exceptions"],
+      "sources": ["startup_task.cpp"],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "conditions": [
+        [
+          "OS=='win'",
+          {
+            "msvs_settings": {
+              "VCCLCompilerTool": {
+                "AdditionalOptions": ["/std:c++20"],
+                "ExceptionHandling": 1
+              }
+            },
+            "msvs_version": "auto",
+            "libraries": ["windowsapp.lib"]
+          }
+        ]
+      ]
+    }
+  ]
+}

package/index.d.ts

@@ -0,0 +1,41 @@
+export enum StartupTaskState {
+  Disabled = 0,
+  DisabledByUser = 1,
+  Enabled = 2,
+  DisabledByPolicy = 3,
+  EnabledByPolicy = 4,
+}
+
+export interface StartupTaskInfo {
+  taskId: string;
+  state: StartupTaskState;
+}
+
+/**
+ * Enable a startup task
+ * @param taskId - The startup task ID (optional, uses first task if not provided)
+ * @returns The resulting state
+ * @throws {Error} If no startup task is found or operation fails
+ */
+export function enable(taskId?: string): Promise<StartupTaskState>;
+
+/**
+ * Disable a startup task
+ * @param taskId - The startup task ID (optional, uses first task if not provided)
+ * @throws {Error} If no startup task is found or operation fails
+ */
+export function disable(taskId?: string): Promise<void>;
+
+/**
+ * Get state of a startup task
+ * @param taskId - The startup task ID (optional, uses first task if not provided)
+ * @returns The current state
+ * @throws {Error} If no startup task is found or operation fails
+ */
+export function getState(taskId?: string): Promise<StartupTaskState>;
+
+/**
+ * Get all startup tasks for the current package
+ * @returns Array of startup task information
+ */
+export function getForCurrentPackage(): Promise<StartupTaskInfo[]>;

package/index.js

@@ -0,0 +1,85 @@
+const binding = global.__WINSTORE_STARTUP_MOCK_BINDING__ || require('node-gyp-build')(__dirname);
+
+/**
+ * Startup task states
+ */
+const StartupTaskState = {
+  Disabled: 0,
+  DisabledByUser: 1,
+  Enabled: 2,
+  DisabledByPolicy: 3,
+  EnabledByPolicy: 4,
+};
+
+/**
+ * Get the first task ID from the current package
+ * @returns {Promise<string|null>}
+ */
+async function getFirstTaskId() {
+  const tasks = await binding.getForCurrentPackage();
+  return tasks.length > 0 ? tasks[0].taskId : null;
+}
+
+/**
+ * Enable a startup task
+ * @param {string} [taskId] - The startup task ID (optional, uses first task if not provided)
+ * @returns {Promise<number>} The resulting state
+ * @throws {Error} If no startup task is found or operation fails
+ */
+async function enable(taskId) {
+  const id = taskId || (await getFirstTaskId());
+  if (!id) {
+    throw new Error(
+      'No startup task found. Ensure your app manifest includes a startup task declaration.',
+    );
+  }
+  return binding.enable(id);
+}
+
+/**
+ * Disable a startup task
+ * @param {string} [taskId] - The startup task ID (optional, uses first task if not provided)
+ * @returns {Promise<void>}
+ * @throws {Error} If no startup task is found or operation fails
+ */
+async function disable(taskId) {
+  const id = taskId || (await getFirstTaskId());
+  if (!id) {
+    throw new Error(
+      'No startup task found. Ensure your app manifest includes a startup task declaration.',
+    );
+  }
+  return binding.disable(id);
+}
+
+/**
+ * Get state of a startup task
+ * @param {string} [taskId] - The startup task ID (optional, uses first task if not provided)
+ * @returns {Promise<number>} The current state
+ * @throws {Error} If no startup task is found or operation fails
+ */
+async function getState(taskId) {
+  const id = taskId || (await getFirstTaskId());
+  if (!id) {
+    throw new Error(
+      'No startup task found. Ensure your app manifest includes a startup task declaration.',
+    );
+  }
+  return binding.getState(id);
+}
+
+/**
+ * Get all startup tasks for the current package
+ * @returns {Promise<Array<{taskId: string, state: number}>>}
+ */
+async function getForCurrentPackage() {
+  return binding.getForCurrentPackage();
+}
+
+module.exports = {
+  enable,
+  disable,
+  getState,
+  getForCurrentPackage,
+  StartupTaskState,
+};

package/lib/binding.js

@@ -0,0 +1,18 @@
+// Allow tests to inject a mock binding
+let binding = global.__WINSTORE_STARTUP_MOCK_BINDING__;
+
+if (!binding) {
+  try {
+    binding = require('../build/Release/winstore_startup.node');
+  } catch (e) {
+    // Fallback for development or non-Windows platforms
+    binding = {
+      enable: () => Promise.reject(new Error('Not supported on this platform')),
+      disable: () => Promise.reject(new Error('Not supported on this platform')),
+      getState: () => Promise.reject(new Error('Not supported on this platform')),
+      getForCurrentPackage: () => Promise.resolve([]),
+    };
+  }
+}
+
+module.exports = binding;

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "winstore-startup",
+  "version": "0.1.0",
+  "description": "Windows Store startup task management using C++/WinRT",
+  "keywords": [
+    "addon",
+    "autostart",
+    "native",
+    "startup",
+    "startup-task",
+    "uwp",
+    "windows",
+    "windows-store",
+    "winrt"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Raghvendra Yadav",
+    "email": "raghvendraa.dev@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aspect-dev/winstore-startup.git"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "startup_task.cpp",
+    "binding.gyp",
+    "lib",
+    "prebuilds"
+  ],
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "install": "node-gyp-build",
+    "prebuild": "prebuildify --napi --strip",
+    "prebuild:all": "prebuildify --napi --strip --arch x64 && prebuildify --napi --strip --arch arm64",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "git clean -fx ./build ./prebuilds ./node_modules"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.5.0",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "oxfmt": "^0.36.0",
+    "oxlint": "^1.51.0",
+    "prebuildify": "^6.0.1",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "gypfile": true
+}

package/startup_task.cpp

@@ -0,0 +1,276 @@
+// startup_task.cpp - WinRT-based startup task addon for Windows Store apps
+#include <napi.h>
+#include <optional>
+#include <string>
+
+#ifdef _WIN32
+#include <winrt/Windows.ApplicationModel.h>
+#include <winrt/Windows.Foundation.h>
+#include <winrt/Windows.Foundation.Collections.h>
+
+using namespace winrt;
+using namespace Windows::ApplicationModel;
+using namespace Windows::Foundation;
+
+// Initialize WinRT apartment on module load
+struct WinRTInitializer {
+  WinRTInitializer() {
+    winrt::init_apartment();
+  }
+  ~WinRTInitializer() {
+    winrt::uninit_apartment();
+  }
+};
+
+static WinRTInitializer g_winrt_init;
+
+// Startup task states (matches Windows.ApplicationModel.StartupTaskState)
+// 0 = Disabled, 1 = DisabledByUser, 2 = Enabled, 3 = DisabledByPolicy, 4 = EnabledByPolicy
+
+// Helper function to validate and extract taskId parameter
+std::optional<std::string> GetTaskIdParam(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "Task ID string expected").ThrowAsJavaScriptException();
+    return std::nullopt;
+  }
+
+  std::string taskId = info[0].As<Napi::String>().Utf8Value();
+  if (taskId.empty()) {
+    Napi::TypeError::New(env, "Task ID cannot be empty").ThrowAsJavaScriptException();
+    return std::nullopt;
+  }
+
+  return taskId;
+}
+
+// Async worker for Enable operation
+class EnableWorker : public Napi::AsyncWorker {
+public:
+  EnableWorker(Napi::Env env, Napi::Promise::Deferred deferred, std::string taskId)
+    : Napi::AsyncWorker(env), deferred_(deferred), taskId_(taskId), state_(-1) {}
+
+  void Execute() override {
+    try {
+      auto task = StartupTask::GetAsync(winrt::to_hstring(taskId_)).get();
+      state_ = static_cast<int>(task.RequestEnableAsync().get());
+    } catch (const winrt::hresult_error& e) {
+      SetError(winrt::to_string(e.message()));
+    }
+  }
+
+  void OnOK() override {
+    deferred_.Resolve(Napi::Number::New(Env(), state_));
+  }
+
+  void OnError(const Napi::Error& error) override {
+    deferred_.Reject(error.Value());
+  }
+
+private:
+  Napi::Promise::Deferred deferred_;
+  std::string taskId_;
+  int state_;
+};
+
+// Async worker for Disable operation
+class DisableWorker : public Napi::AsyncWorker {
+public:
+  DisableWorker(Napi::Env env, Napi::Promise::Deferred deferred, std::string taskId)
+    : Napi::AsyncWorker(env), deferred_(deferred), taskId_(taskId) {}
+
+  void Execute() override {
+    try {
+      auto task = StartupTask::GetAsync(winrt::to_hstring(taskId_)).get();
+      task.Disable();
+    } catch (const winrt::hresult_error& e) {
+      SetError(winrt::to_string(e.message()));
+    }
+  }
+
+  void OnOK() override {
+    deferred_.Resolve(Env().Undefined());
+  }
+
+  void OnError(const Napi::Error& error) override {
+    deferred_.Reject(error.Value());
+  }
+
+private:
+  Napi::Promise::Deferred deferred_;
+  std::string taskId_;
+};
+
+// Async worker for GetState operation
+class GetStateWorker : public Napi::AsyncWorker {
+public:
+  GetStateWorker(Napi::Env env, Napi::Promise::Deferred deferred, std::string taskId)
+    : Napi::AsyncWorker(env), deferred_(deferred), taskId_(taskId), state_(-1) {}
+
+  void Execute() override {
+    try {
+      auto task = StartupTask::GetAsync(winrt::to_hstring(taskId_)).get();
+      state_ = static_cast<int>(task.State());
+    } catch (const winrt::hresult_error& e) {
+      SetError(winrt::to_string(e.message()));
+    }
+  }
+
+  void OnOK() override {
+    deferred_.Resolve(Napi::Number::New(Env(), state_));
+  }
+
+  void OnError(const Napi::Error& error) override {
+    deferred_.Reject(error.Value());
+  }
+
+private:
+  Napi::Promise::Deferred deferred_;
+  std::string taskId_;
+  int state_;
+};
+
+// Async worker for GetForCurrentPackage operation
+struct TaskInfo {
+  std::string taskId;
+  int state;
+};
+
+class GetForCurrentPackageWorker : public Napi::AsyncWorker {
+public:
+  GetForCurrentPackageWorker(Napi::Env env, Napi::Promise::Deferred deferred)
+    : Napi::AsyncWorker(env), deferred_(deferred) {}
+
+  void Execute() override {
+    try {
+      auto tasks = StartupTask::GetForCurrentPackageAsync().get();
+      for (auto const& task : tasks) {
+        TaskInfo info;
+        info.taskId = winrt::to_string(task.TaskId());
+        info.state = static_cast<int>(task.State());
+        tasks_.push_back(info);
+      }
+    } catch (const winrt::hresult_error& e) {
+      SetError(winrt::to_string(e.message()));
+    }
+  }
+
+  void OnOK() override {
+    auto env = Env();
+    auto arr = Napi::Array::New(env, tasks_.size());
+
+    for (size_t i = 0; i < tasks_.size(); i++) {
+      auto obj = Napi::Object::New(env);
+      obj.Set("taskId", Napi::String::New(env, tasks_[i].taskId));
+      obj.Set("state", Napi::Number::New(env, tasks_[i].state));
+      arr[static_cast<uint32_t>(i)] = obj;
+    }
+
+    deferred_.Resolve(arr);
+  }
+
+  void OnError(const Napi::Error& error) override {
+    deferred_.Reject(error.Value());
+  }
+
+private:
+  Napi::Promise::Deferred deferred_;
+  std::vector<TaskInfo> tasks_;
+};
+
+Napi::Value Enable(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+  auto taskIdOpt = GetTaskIdParam(info);
+
+  if (!taskIdOpt.has_value()) {
+    return env.Undefined();
+  }
+
+  auto deferred = Napi::Promise::Deferred::New(env);
+  auto worker = new EnableWorker(env, deferred, taskIdOpt.value());
+  worker->Queue();
+
+  return deferred.Promise();
+}
+
+Napi::Value Disable(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+  auto taskIdOpt = GetTaskIdParam(info);
+
+  if (!taskIdOpt.has_value()) {
+    return env.Undefined();
+  }
+
+  auto deferred = Napi::Promise::Deferred::New(env);
+  auto worker = new DisableWorker(env, deferred, taskIdOpt.value());
+  worker->Queue();
+
+  return deferred.Promise();
+}
+
+Napi::Value GetState(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+  auto taskIdOpt = GetTaskIdParam(info);
+
+  if (!taskIdOpt.has_value()) {
+    return env.Undefined();
+  }
+
+  auto deferred = Napi::Promise::Deferred::New(env);
+  auto worker = new GetStateWorker(env, deferred, taskIdOpt.value());
+  worker->Queue();
+
+  return deferred.Promise();
+}
+
+Napi::Value GetForCurrentPackage(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+
+  auto deferred = Napi::Promise::Deferred::New(env);
+  auto worker = new GetForCurrentPackageWorker(env, deferred);
+  worker->Queue();
+
+  return deferred.Promise();
+}
+
+#else
+// Non-Windows stubs (return rejected promises for consistency)
+Napi::Value Enable(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+  auto deferred = Napi::Promise::Deferred::New(env);
+  deferred.Reject(Napi::Error::New(env, "Not supported on this platform").Value());
+  return deferred.Promise();
+}
+
+Napi::Value Disable(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+  auto deferred = Napi::Promise::Deferred::New(env);
+  deferred.Reject(Napi::Error::New(env, "Not supported on this platform").Value());
+  return deferred.Promise();
+}
+
+Napi::Value GetState(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+  auto deferred = Napi::Promise::Deferred::New(env);
+  deferred.Reject(Napi::Error::New(env, "Not supported on this platform").Value());
+  return deferred.Promise();
+}
+
+Napi::Value GetForCurrentPackage(const Napi::CallbackInfo& info) {
+  auto env = info.Env();
+  auto deferred = Napi::Promise::Deferred::New(env);
+  deferred.Resolve(Napi::Array::New(env, 0));
+  return deferred.Promise();
+}
+#endif
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  exports.Set("enable", Napi::Function::New(env, Enable));
+  exports.Set("disable", Napi::Function::New(env, Disable));
+  exports.Set("getState", Napi::Function::New(env, GetState));
+  exports.Set("getForCurrentPackage", Napi::Function::New(env, GetForCurrentPackage));
+  return exports;
+}
+
+NODE_API_MODULE(winstore_startup, Init)